Mercurial > emacs
annotate doc/emacs/files.texi @ 99015:0941429c2093
Fix last change.
author | Chong Yidong <cyd@stupidchicken.com> |
---|---|
date | Tue, 21 Oct 2008 23:20:55 +0000 |
parents | e05e58449b6e |
children | a3bcaef26adf |
rev | line source |
---|---|
84239 | 1 @c This is part of the Emacs manual. |
2 @c Copyright (C) 1985, 1986, 1987, 1993, 1994, 1995, 1997, 1999, 2000, | |
87903 | 3 @c 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008 Free Software Foundation, Inc. |
84239 | 4 @c See file emacs.texi for copying conditions. |
5 @node Files, Buffers, Keyboard Macros, Top | |
6 @chapter File Handling | |
7 @cindex files | |
8 | |
9 The operating system stores data permanently in named @dfn{files}, so | |
10 most of the text you edit with Emacs comes from a file and is ultimately | |
11 stored in a file. | |
12 | |
13 To edit a file, you must tell Emacs to read the file and prepare a | |
14 buffer containing a copy of the file's text. This is called | |
15 @dfn{visiting} the file. Editing commands apply directly to text in the | |
16 buffer; that is, to the copy inside Emacs. Your changes appear in the | |
17 file itself only when you @dfn{save} the buffer back into the file. | |
18 | |
19 In addition to visiting and saving files, Emacs can delete, copy, | |
20 rename, and append to files, keep multiple versions of them, and operate | |
21 on file directories. | |
22 | |
23 @menu | |
24 * File Names:: How to type and edit file-name arguments. | |
25 * Visiting:: Visiting a file prepares Emacs to edit the file. | |
26 * Saving:: Saving makes your changes permanent. | |
27 * Reverting:: Reverting cancels all the changes not saved. | |
28 @ifnottex | |
29 * Autorevert:: Auto Reverting non-file buffers. | |
30 @end ifnottex | |
31 * Auto Save:: Auto Save periodically protects against loss of data. | |
32 * File Aliases:: Handling multiple names for one file. | |
33 * Version Control:: Version control systems (RCS, CVS and SCCS). | |
34 * Directories:: Creating, deleting, and listing file directories. | |
35 * Comparing Files:: Finding where two files differ. | |
36 * Diff Mode:: Mode for editing file differences. | |
37 * Misc File Ops:: Other things you can do on files. | |
38 * Compressed Files:: Accessing compressed files. | |
39 * File Archives:: Operating on tar, zip, jar etc. archive files. | |
40 * Remote Files:: Accessing files on other sites. | |
41 * Quoted File Names:: Quoting special characters in file names. | |
42 * File Name Cache:: Completion against a list of files you often use. | |
43 * File Conveniences:: Convenience Features for Finding Files. | |
44 * Filesets:: Handling sets of files. | |
45 @end menu | |
46 | |
47 @node File Names | |
48 @section File Names | |
49 @cindex file names | |
50 | |
98636
d7df7c98fed8
(File Names): Reorganize description.
Chong Yidong <cyd@stupidchicken.com>
parents:
98263
diff
changeset
|
51 Many Emacs commands that operate on a file require you to specify |
d7df7c98fed8
(File Names): Reorganize description.
Chong Yidong <cyd@stupidchicken.com>
parents:
98263
diff
changeset
|
52 the file name, using the minibuffer (@pxref{Minibuffer}). You can use |
d7df7c98fed8
(File Names): Reorganize description.
Chong Yidong <cyd@stupidchicken.com>
parents:
98263
diff
changeset
|
53 @dfn{completion} to specify long file names (@pxref{Completion}). |
d7df7c98fed8
(File Names): Reorganize description.
Chong Yidong <cyd@stupidchicken.com>
parents:
98263
diff
changeset
|
54 Note that file name completion ignores file names whose extensions |
d7df7c98fed8
(File Names): Reorganize description.
Chong Yidong <cyd@stupidchicken.com>
parents:
98263
diff
changeset
|
55 appear in the variable @code{completion-ignored-extensions} |
d7df7c98fed8
(File Names): Reorganize description.
Chong Yidong <cyd@stupidchicken.com>
parents:
98263
diff
changeset
|
56 (@pxref{Completion Options}). |
d7df7c98fed8
(File Names): Reorganize description.
Chong Yidong <cyd@stupidchicken.com>
parents:
98263
diff
changeset
|
57 |
d7df7c98fed8
(File Names): Reorganize description.
Chong Yidong <cyd@stupidchicken.com>
parents:
98263
diff
changeset
|
58 For most operations, there is a @dfn{default file name} which is |
d7df7c98fed8
(File Names): Reorganize description.
Chong Yidong <cyd@stupidchicken.com>
parents:
98263
diff
changeset
|
59 used if you type just @key{RET} to enter an empty argument. Normally, |
d7df7c98fed8
(File Names): Reorganize description.
Chong Yidong <cyd@stupidchicken.com>
parents:
98263
diff
changeset
|
60 the default file name is the name of the file visited in the current |
d7df7c98fed8
(File Names): Reorganize description.
Chong Yidong <cyd@stupidchicken.com>
parents:
98263
diff
changeset
|
61 buffer. |
84239 | 62 |
63 @vindex default-directory | |
98636
d7df7c98fed8
(File Names): Reorganize description.
Chong Yidong <cyd@stupidchicken.com>
parents:
98263
diff
changeset
|
64 @vindex insert-default-directory |
d7df7c98fed8
(File Names): Reorganize description.
Chong Yidong <cyd@stupidchicken.com>
parents:
98263
diff
changeset
|
65 Each buffer has a @dfn{default directory} which is normally the same |
d7df7c98fed8
(File Names): Reorganize description.
Chong Yidong <cyd@stupidchicken.com>
parents:
98263
diff
changeset
|
66 as the directory of the file visited in that buffer. For example, if |
d7df7c98fed8
(File Names): Reorganize description.
Chong Yidong <cyd@stupidchicken.com>
parents:
98263
diff
changeset
|
67 the default file name is @file{/u/rms/gnu/gnu.tasks}, the default |
d7df7c98fed8
(File Names): Reorganize description.
Chong Yidong <cyd@stupidchicken.com>
parents:
98263
diff
changeset
|
68 directory is normally @file{/u/rms/gnu/}. The default directory is |
d7df7c98fed8
(File Names): Reorganize description.
Chong Yidong <cyd@stupidchicken.com>
parents:
98263
diff
changeset
|
69 kept in the variable @code{default-directory}, which has a separate |
d7df7c98fed8
(File Names): Reorganize description.
Chong Yidong <cyd@stupidchicken.com>
parents:
98263
diff
changeset
|
70 value in every buffer. When a command reads a file name using the |
d7df7c98fed8
(File Names): Reorganize description.
Chong Yidong <cyd@stupidchicken.com>
parents:
98263
diff
changeset
|
71 minibuffer, the default directory usually serves as the initial |
d7df7c98fed8
(File Names): Reorganize description.
Chong Yidong <cyd@stupidchicken.com>
parents:
98263
diff
changeset
|
72 contents of the minibuffer. To inhibit the insertion of the default |
d7df7c98fed8
(File Names): Reorganize description.
Chong Yidong <cyd@stupidchicken.com>
parents:
98263
diff
changeset
|
73 directory, set the variable @code{insert-default-directory} to |
d7df7c98fed8
(File Names): Reorganize description.
Chong Yidong <cyd@stupidchicken.com>
parents:
98263
diff
changeset
|
74 @code{nil}. |
d7df7c98fed8
(File Names): Reorganize description.
Chong Yidong <cyd@stupidchicken.com>
parents:
98263
diff
changeset
|
75 |
d7df7c98fed8
(File Names): Reorganize description.
Chong Yidong <cyd@stupidchicken.com>
parents:
98263
diff
changeset
|
76 If you enter a file name without a directory, that specifies a file |
d7df7c98fed8
(File Names): Reorganize description.
Chong Yidong <cyd@stupidchicken.com>
parents:
98263
diff
changeset
|
77 in the default directory. If you specify a directory in a relative |
d7df7c98fed8
(File Names): Reorganize description.
Chong Yidong <cyd@stupidchicken.com>
parents:
98263
diff
changeset
|
78 fashion, with a name that does not start with a slash, it is |
d7df7c98fed8
(File Names): Reorganize description.
Chong Yidong <cyd@stupidchicken.com>
parents:
98263
diff
changeset
|
79 interpreted with respect to the default directory. For example, |
d7df7c98fed8
(File Names): Reorganize description.
Chong Yidong <cyd@stupidchicken.com>
parents:
98263
diff
changeset
|
80 suppose the default directory is @file{/u/rms/gnu/}. Entering just |
d7df7c98fed8
(File Names): Reorganize description.
Chong Yidong <cyd@stupidchicken.com>
parents:
98263
diff
changeset
|
81 @samp{foo} in the minibuffer, with a directory omitted, specifies the |
d7df7c98fed8
(File Names): Reorganize description.
Chong Yidong <cyd@stupidchicken.com>
parents:
98263
diff
changeset
|
82 file @file{/u/rms/gnu/foo}; entering @samp{../.login} specifies |
d7df7c98fed8
(File Names): Reorganize description.
Chong Yidong <cyd@stupidchicken.com>
parents:
98263
diff
changeset
|
83 @file{/u/rms/.login}; and entering @samp{new/foo} specifies |
d7df7c98fed8
(File Names): Reorganize description.
Chong Yidong <cyd@stupidchicken.com>
parents:
98263
diff
changeset
|
84 @file{/u/rms/gnu/new/foo}. |
d7df7c98fed8
(File Names): Reorganize description.
Chong Yidong <cyd@stupidchicken.com>
parents:
98263
diff
changeset
|
85 |
d7df7c98fed8
(File Names): Reorganize description.
Chong Yidong <cyd@stupidchicken.com>
parents:
98263
diff
changeset
|
86 When typing a file name into the minibuffer, you can make use of a |
d7df7c98fed8
(File Names): Reorganize description.
Chong Yidong <cyd@stupidchicken.com>
parents:
98263
diff
changeset
|
87 couple of shortcuts: a double slash is interpreted as ``ignore |
d7df7c98fed8
(File Names): Reorganize description.
Chong Yidong <cyd@stupidchicken.com>
parents:
98263
diff
changeset
|
88 everything before the second slash in the pair,'' and @samp{~/} is |
d7df7c98fed8
(File Names): Reorganize description.
Chong Yidong <cyd@stupidchicken.com>
parents:
98263
diff
changeset
|
89 interpreted as your home directory. @xref{Minibuffer File}, for more |
d7df7c98fed8
(File Names): Reorganize description.
Chong Yidong <cyd@stupidchicken.com>
parents:
98263
diff
changeset
|
90 information about these shortcuts. |
84239 | 91 |
92 @findex cd | |
93 @findex pwd | |
98636
d7df7c98fed8
(File Names): Reorganize description.
Chong Yidong <cyd@stupidchicken.com>
parents:
98263
diff
changeset
|
94 The command @kbd{M-x pwd} displays the default directory, and the |
d7df7c98fed8
(File Names): Reorganize description.
Chong Yidong <cyd@stupidchicken.com>
parents:
98263
diff
changeset
|
95 command @kbd{M-x cd} sets it to a value read using the minibuffer. A |
d7df7c98fed8
(File Names): Reorganize description.
Chong Yidong <cyd@stupidchicken.com>
parents:
98263
diff
changeset
|
96 buffer's default directory changes only when the @code{cd} command is |
d7df7c98fed8
(File Names): Reorganize description.
Chong Yidong <cyd@stupidchicken.com>
parents:
98263
diff
changeset
|
97 used. A file-visiting buffer's default directory is initialized to |
d7df7c98fed8
(File Names): Reorganize description.
Chong Yidong <cyd@stupidchicken.com>
parents:
98263
diff
changeset
|
98 the directory of the file it visits. If you create a buffer with |
d7df7c98fed8
(File Names): Reorganize description.
Chong Yidong <cyd@stupidchicken.com>
parents:
98263
diff
changeset
|
99 @kbd{C-x b}, its default directory is copied from that of the buffer |
d7df7c98fed8
(File Names): Reorganize description.
Chong Yidong <cyd@stupidchicken.com>
parents:
98263
diff
changeset
|
100 that was current at the time (@pxref{Select Buffer}). |
84239 | 101 |
102 @cindex environment variables in file names | |
103 @cindex expansion of environment variables | |
104 @cindex @code{$} in file names | |
98636
d7df7c98fed8
(File Names): Reorganize description.
Chong Yidong <cyd@stupidchicken.com>
parents:
98263
diff
changeset
|
105 @anchor{File Names with $}The character @samp{$} is used to |
d7df7c98fed8
(File Names): Reorganize description.
Chong Yidong <cyd@stupidchicken.com>
parents:
98263
diff
changeset
|
106 substitute an environment variable into a file name. The name of the |
d7df7c98fed8
(File Names): Reorganize description.
Chong Yidong <cyd@stupidchicken.com>
parents:
98263
diff
changeset
|
107 environment variable consists of all the alphanumeric characters after |
d7df7c98fed8
(File Names): Reorganize description.
Chong Yidong <cyd@stupidchicken.com>
parents:
98263
diff
changeset
|
108 the @samp{$}; alternatively, it can be enclosed in braces after the |
d7df7c98fed8
(File Names): Reorganize description.
Chong Yidong <cyd@stupidchicken.com>
parents:
98263
diff
changeset
|
109 @samp{$}. For example, if you have used the shell command |
d7df7c98fed8
(File Names): Reorganize description.
Chong Yidong <cyd@stupidchicken.com>
parents:
98263
diff
changeset
|
110 @command{export FOO=rms/hacks} to set up an environment variable named |
d7df7c98fed8
(File Names): Reorganize description.
Chong Yidong <cyd@stupidchicken.com>
parents:
98263
diff
changeset
|
111 @env{FOO}, then both @file{/u/$FOO/test.c} and |
d7df7c98fed8
(File Names): Reorganize description.
Chong Yidong <cyd@stupidchicken.com>
parents:
98263
diff
changeset
|
112 @file{/u/$@{FOO@}/test.c} are abbreviations for |
d7df7c98fed8
(File Names): Reorganize description.
Chong Yidong <cyd@stupidchicken.com>
parents:
98263
diff
changeset
|
113 @file{/u/rms/hacks/test.c}. If the environment variable is not |
d7df7c98fed8
(File Names): Reorganize description.
Chong Yidong <cyd@stupidchicken.com>
parents:
98263
diff
changeset
|
114 defined, no substitution occurs, so that the character @samp{$} stands |
d7df7c98fed8
(File Names): Reorganize description.
Chong Yidong <cyd@stupidchicken.com>
parents:
98263
diff
changeset
|
115 for itself. |
d7df7c98fed8
(File Names): Reorganize description.
Chong Yidong <cyd@stupidchicken.com>
parents:
98263
diff
changeset
|
116 |
d7df7c98fed8
(File Names): Reorganize description.
Chong Yidong <cyd@stupidchicken.com>
parents:
98263
diff
changeset
|
117 Note that environment variables affect Emacs only if they are |
d7df7c98fed8
(File Names): Reorganize description.
Chong Yidong <cyd@stupidchicken.com>
parents:
98263
diff
changeset
|
118 applied before Emacs is started. |
84239 | 119 |
120 To access a file with @samp{$} in its name, if the @samp{$} causes | |
121 expansion, type @samp{$$}. This pair is converted to a single | |
98636
d7df7c98fed8
(File Names): Reorganize description.
Chong Yidong <cyd@stupidchicken.com>
parents:
98263
diff
changeset
|
122 @samp{$} at the same time that variable substitution is performed for |
d7df7c98fed8
(File Names): Reorganize description.
Chong Yidong <cyd@stupidchicken.com>
parents:
98263
diff
changeset
|
123 a single @samp{$}. Alternatively, quote the whole file name with |
84239 | 124 @samp{/:} (@pxref{Quoted File Names}). File names which begin with a |
125 literal @samp{~} should also be quoted with @samp{/:}. | |
126 | |
127 You can include non-@acronym{ASCII} characters in file names if you set the | |
128 variable @code{file-name-coding-system} to a non-@code{nil} value. | |
129 @xref{File Name Coding}. | |
130 | |
131 @node Visiting | |
132 @section Visiting Files | |
133 @cindex visiting files | |
134 @cindex open file | |
135 | |
136 @table @kbd | |
137 @item C-x C-f | |
138 Visit a file (@code{find-file}). | |
139 @item C-x C-r | |
140 Visit a file for viewing, without allowing changes to it | |
141 (@code{find-file-read-only}). | |
142 @item C-x C-v | |
143 Visit a different file instead of the one visited last | |
144 (@code{find-alternate-file}). | |
145 @item C-x 4 f | |
146 Visit a file, in another window (@code{find-file-other-window}). Don't | |
147 alter what is displayed in the selected window. | |
148 @item C-x 5 f | |
149 Visit a file, in a new frame (@code{find-file-other-frame}). Don't | |
150 alter what is displayed in the selected frame. | |
151 @item M-x find-file-literally | |
152 Visit a file with no conversion of the contents. | |
153 @end table | |
154 | |
155 @cindex files, visiting and saving | |
156 @cindex saving files | |
157 @dfn{Visiting} a file means reading its contents into an Emacs | |
158 buffer so you can edit them. Emacs makes a new buffer for each file | |
98636
d7df7c98fed8
(File Names): Reorganize description.
Chong Yidong <cyd@stupidchicken.com>
parents:
98263
diff
changeset
|
159 that you visit. |
d7df7c98fed8
(File Names): Reorganize description.
Chong Yidong <cyd@stupidchicken.com>
parents:
98263
diff
changeset
|
160 |
d7df7c98fed8
(File Names): Reorganize description.
Chong Yidong <cyd@stupidchicken.com>
parents:
98263
diff
changeset
|
161 Emacs normally constructs the buffer name from the file name, |
d7df7c98fed8
(File Names): Reorganize description.
Chong Yidong <cyd@stupidchicken.com>
parents:
98263
diff
changeset
|
162 omitting the directory name. For example, a file named |
d7df7c98fed8
(File Names): Reorganize description.
Chong Yidong <cyd@stupidchicken.com>
parents:
98263
diff
changeset
|
163 @file{/usr/rms/emacs.tex} is visited in a buffer named |
d7df7c98fed8
(File Names): Reorganize description.
Chong Yidong <cyd@stupidchicken.com>
parents:
98263
diff
changeset
|
164 @samp{emacs.tex}. If there is already a buffer with that name, Emacs |
d7df7c98fed8
(File Names): Reorganize description.
Chong Yidong <cyd@stupidchicken.com>
parents:
98263
diff
changeset
|
165 constructs a unique name; the normal method is to append @samp{<2>}, |
d7df7c98fed8
(File Names): Reorganize description.
Chong Yidong <cyd@stupidchicken.com>
parents:
98263
diff
changeset
|
166 @samp{<3>}, and so on, but you can select other methods. |
d7df7c98fed8
(File Names): Reorganize description.
Chong Yidong <cyd@stupidchicken.com>
parents:
98263
diff
changeset
|
167 @xref{Uniquify}. |
d7df7c98fed8
(File Names): Reorganize description.
Chong Yidong <cyd@stupidchicken.com>
parents:
98263
diff
changeset
|
168 |
d7df7c98fed8
(File Names): Reorganize description.
Chong Yidong <cyd@stupidchicken.com>
parents:
98263
diff
changeset
|
169 Each window's mode line shows the name of the buffer that is being |
d7df7c98fed8
(File Names): Reorganize description.
Chong Yidong <cyd@stupidchicken.com>
parents:
98263
diff
changeset
|
170 displayed in that window, so you can always tell what buffer you are |
d7df7c98fed8
(File Names): Reorganize description.
Chong Yidong <cyd@stupidchicken.com>
parents:
98263
diff
changeset
|
171 editing. @pxref{Mode Line}. |
84239 | 172 |
173 The changes you make with editing commands are made in the Emacs | |
174 buffer. They do not take effect in the file that you visited, or any | |
98636
d7df7c98fed8
(File Names): Reorganize description.
Chong Yidong <cyd@stupidchicken.com>
parents:
98263
diff
changeset
|
175 permanent place, until you @dfn{save} the buffer (@pxref{Saving}). |
84239 | 176 |
177 @cindex modified (buffer) | |
178 If a buffer contains changes that have not been saved, we say the | |
98636
d7df7c98fed8
(File Names): Reorganize description.
Chong Yidong <cyd@stupidchicken.com>
parents:
98263
diff
changeset
|
179 buffer is @dfn{modified}. This implies that some changes will be lost |
d7df7c98fed8
(File Names): Reorganize description.
Chong Yidong <cyd@stupidchicken.com>
parents:
98263
diff
changeset
|
180 if the buffer is not saved. The mode line displays two stars near the |
d7df7c98fed8
(File Names): Reorganize description.
Chong Yidong <cyd@stupidchicken.com>
parents:
98263
diff
changeset
|
181 left margin to indicate that the buffer is modified. |
84239 | 182 |
183 @kindex C-x C-f | |
184 @findex find-file | |
98636
d7df7c98fed8
(File Names): Reorganize description.
Chong Yidong <cyd@stupidchicken.com>
parents:
98263
diff
changeset
|
185 To visit a file, type @kbd{C-x C-f} (@code{find-file}) and use the |
d7df7c98fed8
(File Names): Reorganize description.
Chong Yidong <cyd@stupidchicken.com>
parents:
98263
diff
changeset
|
186 minibuffer to enter the name of the desired file. The usual |
d7df7c98fed8
(File Names): Reorganize description.
Chong Yidong <cyd@stupidchicken.com>
parents:
98263
diff
changeset
|
187 defaulting and completion behavior is available in this minibuffer |
d7df7c98fed8
(File Names): Reorganize description.
Chong Yidong <cyd@stupidchicken.com>
parents:
98263
diff
changeset
|
188 (@pxref{Minibuffer File}). Note, also, that completion ignores |
d7df7c98fed8
(File Names): Reorganize description.
Chong Yidong <cyd@stupidchicken.com>
parents:
98263
diff
changeset
|
189 certain file names (@pxref{Completion Options}). While in the |
d7df7c98fed8
(File Names): Reorganize description.
Chong Yidong <cyd@stupidchicken.com>
parents:
98263
diff
changeset
|
190 minibuffer, you can abort @kbd{C-x C-f} by typing @kbd{C-g}. |
d7df7c98fed8
(File Names): Reorganize description.
Chong Yidong <cyd@stupidchicken.com>
parents:
98263
diff
changeset
|
191 |
d7df7c98fed8
(File Names): Reorganize description.
Chong Yidong <cyd@stupidchicken.com>
parents:
98263
diff
changeset
|
192 Your can tell that @kbd{C-x C-f} has completed successfully by the |
d7df7c98fed8
(File Names): Reorganize description.
Chong Yidong <cyd@stupidchicken.com>
parents:
98263
diff
changeset
|
193 appearance of new text on the screen and a new buffer name in the mode |
d7df7c98fed8
(File Names): Reorganize description.
Chong Yidong <cyd@stupidchicken.com>
parents:
98263
diff
changeset
|
194 line. If the specified file does not exist and you could not create |
d7df7c98fed8
(File Names): Reorganize description.
Chong Yidong <cyd@stupidchicken.com>
parents:
98263
diff
changeset
|
195 it, or exists but you can't read it, an error message is displayed in |
d7df7c98fed8
(File Names): Reorganize description.
Chong Yidong <cyd@stupidchicken.com>
parents:
98263
diff
changeset
|
196 the echo area. |
84239 | 197 |
198 If you visit a file that is already in Emacs, @kbd{C-x C-f} does not make | |
199 another copy. It selects the existing buffer containing that file. | |
200 However, before doing so, it checks whether the file itself has changed | |
201 since you visited or saved it last. If the file has changed, Emacs offers | |
202 to reread it. | |
203 | |
204 @vindex large-file-warning-threshold | |
205 @cindex maximum buffer size exceeded, error message | |
206 If you try to visit a file larger than | |
207 @code{large-file-warning-threshold} (the default is 10000000, which is | |
98636
d7df7c98fed8
(File Names): Reorganize description.
Chong Yidong <cyd@stupidchicken.com>
parents:
98263
diff
changeset
|
208 about 10 megabytes), Emacs asks you for confirmation first. You can |
d7df7c98fed8
(File Names): Reorganize description.
Chong Yidong <cyd@stupidchicken.com>
parents:
98263
diff
changeset
|
209 answer @kbd{y} to proceed with visiting the file. Note, however, that |
d7df7c98fed8
(File Names): Reorganize description.
Chong Yidong <cyd@stupidchicken.com>
parents:
98263
diff
changeset
|
210 Emacs cannot visit files that are larger than the maximum Emacs buffer |
d7df7c98fed8
(File Names): Reorganize description.
Chong Yidong <cyd@stupidchicken.com>
parents:
98263
diff
changeset
|
211 size, which is around 256 megabytes on 32-bit machines |
84239 | 212 (@pxref{Buffers}). If you try, Emacs will display an error message |
213 saying that the maximum buffer size has been exceeded. | |
214 | |
215 @cindex wildcard characters in file names | |
216 @vindex find-file-wildcards | |
217 If the file name you specify contains shell-style wildcard | |
218 characters, Emacs visits all the files that match it. (On | |
219 case-insensitive filesystems, Emacs matches the wildcards disregarding | |
220 the letter case.) Wildcards include @samp{?}, @samp{*}, and | |
221 @samp{[@dots{}]} sequences. To enter the wild card @samp{?} in a file | |
222 name in the minibuffer, you need to type @kbd{C-q ?}. @xref{Quoted | |
223 File Names}, for information on how to visit a file whose name | |
224 actually contains wildcard characters. You can disable the wildcard | |
225 feature by customizing @code{find-file-wildcards}. | |
226 | |
98636
d7df7c98fed8
(File Names): Reorganize description.
Chong Yidong <cyd@stupidchicken.com>
parents:
98263
diff
changeset
|
227 @cindex file selection dialog |
d7df7c98fed8
(File Names): Reorganize description.
Chong Yidong <cyd@stupidchicken.com>
parents:
98263
diff
changeset
|
228 On graphical displays, there are two additional methods for visiting |
d7df7c98fed8
(File Names): Reorganize description.
Chong Yidong <cyd@stupidchicken.com>
parents:
98263
diff
changeset
|
229 files. Firstly, when Emacs is built with a suitable GUI toolkit, |
d7df7c98fed8
(File Names): Reorganize description.
Chong Yidong <cyd@stupidchicken.com>
parents:
98263
diff
changeset
|
230 commands invoked with the mouse (by clicking on the menu bar or tool |
d7df7c98fed8
(File Names): Reorganize description.
Chong Yidong <cyd@stupidchicken.com>
parents:
98263
diff
changeset
|
231 bar) use the toolkit's standard ``File Selection'' dialog instead of |
d7df7c98fed8
(File Names): Reorganize description.
Chong Yidong <cyd@stupidchicken.com>
parents:
98263
diff
changeset
|
232 prompting for the file name in the minibuffer. On GNU/Linux and Unix |
d7df7c98fed8
(File Names): Reorganize description.
Chong Yidong <cyd@stupidchicken.com>
parents:
98263
diff
changeset
|
233 platforms, Emacs does this when built with GTK, LessTif, and Motif |
d7df7c98fed8
(File Names): Reorganize description.
Chong Yidong <cyd@stupidchicken.com>
parents:
98263
diff
changeset
|
234 toolkits; on MS-Windows and Mac, the GUI version does that by default. |
d7df7c98fed8
(File Names): Reorganize description.
Chong Yidong <cyd@stupidchicken.com>
parents:
98263
diff
changeset
|
235 For information on how to customize this, see @ref{Dialog Boxes}. |
d7df7c98fed8
(File Names): Reorganize description.
Chong Yidong <cyd@stupidchicken.com>
parents:
98263
diff
changeset
|
236 |
d7df7c98fed8
(File Names): Reorganize description.
Chong Yidong <cyd@stupidchicken.com>
parents:
98263
diff
changeset
|
237 Secondly, Emacs supports ``drag and drop'': dropping a file into an |
d7df7c98fed8
(File Names): Reorganize description.
Chong Yidong <cyd@stupidchicken.com>
parents:
98263
diff
changeset
|
238 ordinary Emacs window visits the file using that window. As an |
d7df7c98fed8
(File Names): Reorganize description.
Chong Yidong <cyd@stupidchicken.com>
parents:
98263
diff
changeset
|
239 exception, dropping a file into a window displaying a Dired buffer |
d7df7c98fed8
(File Names): Reorganize description.
Chong Yidong <cyd@stupidchicken.com>
parents:
98263
diff
changeset
|
240 moves or copies the file into the displayed directory. For details, |
d7df7c98fed8
(File Names): Reorganize description.
Chong Yidong <cyd@stupidchicken.com>
parents:
98263
diff
changeset
|
241 see @ref{Drag and Drop}, and @ref{Misc Dired Features}. |
d7df7c98fed8
(File Names): Reorganize description.
Chong Yidong <cyd@stupidchicken.com>
parents:
98263
diff
changeset
|
242 |
d7df7c98fed8
(File Names): Reorganize description.
Chong Yidong <cyd@stupidchicken.com>
parents:
98263
diff
changeset
|
243 @cindex creating files |
99002
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
244 @vindex find-file-confirm-nonexistent-file |
98636
d7df7c98fed8
(File Names): Reorganize description.
Chong Yidong <cyd@stupidchicken.com>
parents:
98263
diff
changeset
|
245 What if you want to create a new file? Just visit it. Emacs |
d7df7c98fed8
(File Names): Reorganize description.
Chong Yidong <cyd@stupidchicken.com>
parents:
98263
diff
changeset
|
246 displays @samp{(New file)} in the echo area, but in other respects |
d7df7c98fed8
(File Names): Reorganize description.
Chong Yidong <cyd@stupidchicken.com>
parents:
98263
diff
changeset
|
247 behaves as if you had visited an existing empty file. If you make |
99002
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
248 changes and save them, the file is created. If you change the |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
249 variable @code{find-file-confirm-nonexistent-file} to @code{t}, then |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
250 Emacs prompts you for confirmation before visiting a non-existent |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
251 file. |
98636
d7df7c98fed8
(File Names): Reorganize description.
Chong Yidong <cyd@stupidchicken.com>
parents:
98263
diff
changeset
|
252 |
d7df7c98fed8
(File Names): Reorganize description.
Chong Yidong <cyd@stupidchicken.com>
parents:
98263
diff
changeset
|
253 @kindex C-x C-v |
d7df7c98fed8
(File Names): Reorganize description.
Chong Yidong <cyd@stupidchicken.com>
parents:
98263
diff
changeset
|
254 @findex find-alternate-file |
d7df7c98fed8
(File Names): Reorganize description.
Chong Yidong <cyd@stupidchicken.com>
parents:
98263
diff
changeset
|
255 If you visit a nonexistent file unintentionally (because you typed |
d7df7c98fed8
(File Names): Reorganize description.
Chong Yidong <cyd@stupidchicken.com>
parents:
98263
diff
changeset
|
256 the wrong file name), type @kbd{C-x C-v} (@code{find-alternate-file}) |
d7df7c98fed8
(File Names): Reorganize description.
Chong Yidong <cyd@stupidchicken.com>
parents:
98263
diff
changeset
|
257 to visit the file you really wanted. @kbd{C-x C-v} is similar to |
d7df7c98fed8
(File Names): Reorganize description.
Chong Yidong <cyd@stupidchicken.com>
parents:
98263
diff
changeset
|
258 @kbd{C-x C-f}, but it kills the current buffer (after first offering |
d7df7c98fed8
(File Names): Reorganize description.
Chong Yidong <cyd@stupidchicken.com>
parents:
98263
diff
changeset
|
259 to save it if it is modified). When @kbd{C-x C-v} reads the file name |
d7df7c98fed8
(File Names): Reorganize description.
Chong Yidong <cyd@stupidchicken.com>
parents:
98263
diff
changeset
|
260 to visit, it inserts the entire default file name in the buffer, with |
d7df7c98fed8
(File Names): Reorganize description.
Chong Yidong <cyd@stupidchicken.com>
parents:
98263
diff
changeset
|
261 point just after the directory part; this is convenient if you made a |
d7df7c98fed8
(File Names): Reorganize description.
Chong Yidong <cyd@stupidchicken.com>
parents:
98263
diff
changeset
|
262 slight error in typing the name. |
d7df7c98fed8
(File Names): Reorganize description.
Chong Yidong <cyd@stupidchicken.com>
parents:
98263
diff
changeset
|
263 |
d7df7c98fed8
(File Names): Reorganize description.
Chong Yidong <cyd@stupidchicken.com>
parents:
98263
diff
changeset
|
264 @vindex find-file-run-dired |
d7df7c98fed8
(File Names): Reorganize description.
Chong Yidong <cyd@stupidchicken.com>
parents:
98263
diff
changeset
|
265 If you ``visit'' a file that is actually a directory, Emacs invokes |
d7df7c98fed8
(File Names): Reorganize description.
Chong Yidong <cyd@stupidchicken.com>
parents:
98263
diff
changeset
|
266 Dired, the Emacs directory browser; this lets you you ``edit'' the |
d7df7c98fed8
(File Names): Reorganize description.
Chong Yidong <cyd@stupidchicken.com>
parents:
98263
diff
changeset
|
267 contents of the directory. @xref{Dired}. You can disable this |
d7df7c98fed8
(File Names): Reorganize description.
Chong Yidong <cyd@stupidchicken.com>
parents:
98263
diff
changeset
|
268 behavior by setting the variable @code{find-file-run-dired} to |
d7df7c98fed8
(File Names): Reorganize description.
Chong Yidong <cyd@stupidchicken.com>
parents:
98263
diff
changeset
|
269 @code{nil}; in that case, it is an error to try to visit a directory. |
d7df7c98fed8
(File Names): Reorganize description.
Chong Yidong <cyd@stupidchicken.com>
parents:
98263
diff
changeset
|
270 |
d7df7c98fed8
(File Names): Reorganize description.
Chong Yidong <cyd@stupidchicken.com>
parents:
98263
diff
changeset
|
271 Files which are actually collections of other files, or @dfn{file |
d7df7c98fed8
(File Names): Reorganize description.
Chong Yidong <cyd@stupidchicken.com>
parents:
98263
diff
changeset
|
272 archives}, are visited in special modes which invoke a Dired-like |
d7df7c98fed8
(File Names): Reorganize description.
Chong Yidong <cyd@stupidchicken.com>
parents:
98263
diff
changeset
|
273 environment to allow operations on archive members. @xref{File |
d7df7c98fed8
(File Names): Reorganize description.
Chong Yidong <cyd@stupidchicken.com>
parents:
98263
diff
changeset
|
274 Archives}, for more about these features. |
d7df7c98fed8
(File Names): Reorganize description.
Chong Yidong <cyd@stupidchicken.com>
parents:
98263
diff
changeset
|
275 |
84239 | 276 If you visit a file that the operating system won't let you modify, |
277 or that is marked read-only, Emacs makes the buffer read-only too, so | |
278 that you won't go ahead and make changes that you'll have trouble | |
279 saving afterward. You can make the buffer writable with @kbd{C-x C-q} | |
280 (@code{toggle-read-only}). @xref{Misc Buffer}. | |
281 | |
282 @kindex C-x C-r | |
283 @findex find-file-read-only | |
284 If you want to visit a file as read-only in order to protect | |
285 yourself from entering changes accidentally, visit it with the command | |
286 @kbd{C-x C-r} (@code{find-file-read-only}) instead of @kbd{C-x C-f}. | |
287 | |
288 @kindex C-x 4 f | |
289 @findex find-file-other-window | |
290 @kbd{C-x 4 f} (@code{find-file-other-window}) is like @kbd{C-x C-f} | |
291 except that the buffer containing the specified file is selected in another | |
292 window. The window that was selected before @kbd{C-x 4 f} continues to | |
293 show the same buffer it was already showing. If this command is used when | |
294 only one window is being displayed, that window is split in two, with one | |
295 window showing the same buffer as before, and the other one showing the | |
296 newly requested file. @xref{Windows}. | |
297 | |
298 @kindex C-x 5 f | |
299 @findex find-file-other-frame | |
300 @kbd{C-x 5 f} (@code{find-file-other-frame}) is similar, but opens a | |
301 new frame, or makes visible any existing frame showing the file you | |
302 seek. This feature is available only when you are using a window | |
303 system. @xref{Frames}. | |
304 | |
98636
d7df7c98fed8
(File Names): Reorganize description.
Chong Yidong <cyd@stupidchicken.com>
parents:
98263
diff
changeset
|
305 Emacs recognizes from the contents of a file which end-of-line |
d7df7c98fed8
(File Names): Reorganize description.
Chong Yidong <cyd@stupidchicken.com>
parents:
98263
diff
changeset
|
306 convention it uses to separate lines---newline (used on GNU/Linux and |
d7df7c98fed8
(File Names): Reorganize description.
Chong Yidong <cyd@stupidchicken.com>
parents:
98263
diff
changeset
|
307 on Unix), carriage-return linefeed (used on Microsoft systems), or |
d7df7c98fed8
(File Names): Reorganize description.
Chong Yidong <cyd@stupidchicken.com>
parents:
98263
diff
changeset
|
308 just carriage-return (used on the Macintosh)---and automatically |
d7df7c98fed8
(File Names): Reorganize description.
Chong Yidong <cyd@stupidchicken.com>
parents:
98263
diff
changeset
|
309 converts the contents to the normal Emacs convention, which is that |
d7df7c98fed8
(File Names): Reorganize description.
Chong Yidong <cyd@stupidchicken.com>
parents:
98263
diff
changeset
|
310 the newline character separates lines. This is a part of the general |
d7df7c98fed8
(File Names): Reorganize description.
Chong Yidong <cyd@stupidchicken.com>
parents:
98263
diff
changeset
|
311 feature of coding system conversion (@pxref{Coding Systems}), and |
d7df7c98fed8
(File Names): Reorganize description.
Chong Yidong <cyd@stupidchicken.com>
parents:
98263
diff
changeset
|
312 makes it possible to edit files imported from different operating |
d7df7c98fed8
(File Names): Reorganize description.
Chong Yidong <cyd@stupidchicken.com>
parents:
98263
diff
changeset
|
313 systems with equal convenience. If you change the text and save the |
d7df7c98fed8
(File Names): Reorganize description.
Chong Yidong <cyd@stupidchicken.com>
parents:
98263
diff
changeset
|
314 file, Emacs performs the inverse conversion, changing newlines back |
d7df7c98fed8
(File Names): Reorganize description.
Chong Yidong <cyd@stupidchicken.com>
parents:
98263
diff
changeset
|
315 into carriage-return linefeed or just carriage-return if appropriate. |
d7df7c98fed8
(File Names): Reorganize description.
Chong Yidong <cyd@stupidchicken.com>
parents:
98263
diff
changeset
|
316 |
84239 | 317 @findex find-file-literally |
98636
d7df7c98fed8
(File Names): Reorganize description.
Chong Yidong <cyd@stupidchicken.com>
parents:
98263
diff
changeset
|
318 If you wish to edit a file as a sequence of @acronym{ASCII} |
d7df7c98fed8
(File Names): Reorganize description.
Chong Yidong <cyd@stupidchicken.com>
parents:
98263
diff
changeset
|
319 characters with no special encoding or conversion, use the @kbd{M-x |
d7df7c98fed8
(File Names): Reorganize description.
Chong Yidong <cyd@stupidchicken.com>
parents:
98263
diff
changeset
|
320 find-file-literally} command. This visits a file, like @kbd{C-x C-f}, |
d7df7c98fed8
(File Names): Reorganize description.
Chong Yidong <cyd@stupidchicken.com>
parents:
98263
diff
changeset
|
321 but does not do format conversion (@pxref{Formatted Text}), character |
d7df7c98fed8
(File Names): Reorganize description.
Chong Yidong <cyd@stupidchicken.com>
parents:
98263
diff
changeset
|
322 code conversion (@pxref{Coding Systems}), or automatic uncompression |
d7df7c98fed8
(File Names): Reorganize description.
Chong Yidong <cyd@stupidchicken.com>
parents:
98263
diff
changeset
|
323 (@pxref{Compressed Files}), and does not add a final newline because |
d7df7c98fed8
(File Names): Reorganize description.
Chong Yidong <cyd@stupidchicken.com>
parents:
98263
diff
changeset
|
324 of @code{require-final-newline} (@pxref{Customize Save}). If you have |
d7df7c98fed8
(File Names): Reorganize description.
Chong Yidong <cyd@stupidchicken.com>
parents:
98263
diff
changeset
|
325 already visited the same file in the usual (non-literal) manner, this |
d7df7c98fed8
(File Names): Reorganize description.
Chong Yidong <cyd@stupidchicken.com>
parents:
98263
diff
changeset
|
326 command asks you whether to visit it literally instead. |
84239 | 327 |
328 @vindex find-file-hook | |
329 @vindex find-file-not-found-functions | |
330 Two special hook variables allow extensions to modify the operation of | |
331 visiting files. Visiting a file that does not exist runs the functions | |
332 in the list @code{find-file-not-found-functions}; this variable holds a list | |
333 of functions, and the functions are called one by one (with no | |
334 arguments) until one of them returns non-@code{nil}. This is not a | |
335 normal hook, and the name ends in @samp{-functions} rather than @samp{-hook} | |
336 to indicate that fact. | |
337 | |
338 Successful visiting of any file, whether existing or not, calls the | |
339 functions in the list @code{find-file-hook}, with no arguments. | |
340 This variable is a normal hook. In the case of a nonexistent file, the | |
341 @code{find-file-not-found-functions} are run first. @xref{Hooks}. | |
342 | |
343 There are several ways to specify automatically the major mode for | |
344 editing the file (@pxref{Choosing Modes}), and to specify local | |
345 variables defined for that file (@pxref{File Variables}). | |
346 | |
347 @node Saving | |
348 @section Saving Files | |
349 | |
350 @dfn{Saving} a buffer in Emacs means writing its contents back into the file | |
351 that was visited in the buffer. | |
352 | |
353 @menu | |
354 * Save Commands:: Commands for saving files. | |
355 * Backup:: How Emacs saves the old version of your file. | |
356 * Customize Save:: Customizing the saving of files. | |
357 * Interlocking:: How Emacs protects against simultaneous editing | |
358 of one file by two users. | |
359 * Shadowing: File Shadowing. Copying files to "shadows" automatically. | |
360 * Time Stamps:: Emacs can update time stamps on saved files. | |
361 @end menu | |
362 | |
363 @node Save Commands | |
364 @subsection Commands for Saving Files | |
365 | |
366 These are the commands that relate to saving and writing files. | |
367 | |
368 @table @kbd | |
369 @item C-x C-s | |
370 Save the current buffer in its visited file on disk (@code{save-buffer}). | |
371 @item C-x s | |
372 Save any or all buffers in their visited files (@code{save-some-buffers}). | |
373 @item M-~ | |
374 Forget that the current buffer has been changed (@code{not-modified}). | |
375 With prefix argument (@kbd{C-u}), mark the current buffer as changed. | |
376 @item C-x C-w | |
377 Save the current buffer with a specified file name (@code{write-file}). | |
378 @item M-x set-visited-file-name | |
379 Change the file name under which the current buffer will be saved. | |
380 @end table | |
381 | |
382 @kindex C-x C-s | |
383 @findex save-buffer | |
384 When you wish to save the file and make your changes permanent, type | |
385 @kbd{C-x C-s} (@code{save-buffer}). After saving is finished, @kbd{C-x C-s} | |
386 displays a message like this: | |
387 | |
388 @example | |
389 Wrote /u/rms/gnu/gnu.tasks | |
390 @end example | |
391 | |
392 @noindent | |
393 If the selected buffer is not modified (no changes have been made in it | |
394 since the buffer was created or last saved), saving is not really done, | |
395 because it would have no effect. Instead, @kbd{C-x C-s} displays a message | |
396 like this in the echo area: | |
397 | |
398 @example | |
399 (No changes need to be saved) | |
400 @end example | |
401 | |
98636
d7df7c98fed8
(File Names): Reorganize description.
Chong Yidong <cyd@stupidchicken.com>
parents:
98263
diff
changeset
|
402 With a prefix argument, @kbd{C-u C-x C-s}, Emacs also marks the buffer |
d7df7c98fed8
(File Names): Reorganize description.
Chong Yidong <cyd@stupidchicken.com>
parents:
98263
diff
changeset
|
403 to be backed up when the next save is done. @xref{Backup}. |
d7df7c98fed8
(File Names): Reorganize description.
Chong Yidong <cyd@stupidchicken.com>
parents:
98263
diff
changeset
|
404 |
84239 | 405 @kindex C-x s |
406 @findex save-some-buffers | |
407 The command @kbd{C-x s} (@code{save-some-buffers}) offers to save any | |
408 or all modified buffers. It asks you what to do with each buffer. The | |
409 possible responses are analogous to those of @code{query-replace}: | |
410 | |
411 @table @kbd | |
412 @item y | |
413 Save this buffer and ask about the rest of the buffers. | |
414 @item n | |
415 Don't save this buffer, but ask about the rest of the buffers. | |
416 @item ! | |
417 Save this buffer and all the rest with no more questions. | |
418 @c following generates acceptable underfull hbox | |
419 @item @key{RET} | |
420 Terminate @code{save-some-buffers} without any more saving. | |
421 @item . | |
422 Save this buffer, then exit @code{save-some-buffers} without even asking | |
423 about other buffers. | |
424 @item C-r | |
425 View the buffer that you are currently being asked about. When you exit | |
426 View mode, you get back to @code{save-some-buffers}, which asks the | |
427 question again. | |
428 @item d | |
429 Diff the buffer against its corresponding file, so you can see | |
430 what changes you would be saving. | |
431 @item C-h | |
432 Display a help message about these options. | |
433 @end table | |
434 | |
435 @kbd{C-x C-c}, the key sequence to exit Emacs, invokes | |
436 @code{save-some-buffers} and therefore asks the same questions. | |
437 | |
438 @kindex M-~ | |
439 @findex not-modified | |
98636
d7df7c98fed8
(File Names): Reorganize description.
Chong Yidong <cyd@stupidchicken.com>
parents:
98263
diff
changeset
|
440 If you have changed a buffer but do not wish to save the changes, |
d7df7c98fed8
(File Names): Reorganize description.
Chong Yidong <cyd@stupidchicken.com>
parents:
98263
diff
changeset
|
441 you should take some action to prevent it. Otherwise, each time you |
d7df7c98fed8
(File Names): Reorganize description.
Chong Yidong <cyd@stupidchicken.com>
parents:
98263
diff
changeset
|
442 use @kbd{C-x s} or @kbd{C-x C-c}, you are liable to save this buffer |
d7df7c98fed8
(File Names): Reorganize description.
Chong Yidong <cyd@stupidchicken.com>
parents:
98263
diff
changeset
|
443 by mistake. One thing you can do is type @kbd{M-~} |
d7df7c98fed8
(File Names): Reorganize description.
Chong Yidong <cyd@stupidchicken.com>
parents:
98263
diff
changeset
|
444 (@code{not-modified}), which clears out the indication that the buffer |
d7df7c98fed8
(File Names): Reorganize description.
Chong Yidong <cyd@stupidchicken.com>
parents:
98263
diff
changeset
|
445 is modified. If you do this, none of the save commands will believe |
d7df7c98fed8
(File Names): Reorganize description.
Chong Yidong <cyd@stupidchicken.com>
parents:
98263
diff
changeset
|
446 that the buffer needs to be saved. (@samp{~} is often used as a |
d7df7c98fed8
(File Names): Reorganize description.
Chong Yidong <cyd@stupidchicken.com>
parents:
98263
diff
changeset
|
447 mathematical symbol for `not'; thus @kbd{M-~} is `not', metafied.) |
84239 | 448 Alternatively, you can cancel all the changes made since the file was |
449 visited or saved, by reading the text from the file again. This is | |
98636
d7df7c98fed8
(File Names): Reorganize description.
Chong Yidong <cyd@stupidchicken.com>
parents:
98263
diff
changeset
|
450 called @dfn{reverting}. @xref{Reverting}. (You could also undo all |
d7df7c98fed8
(File Names): Reorganize description.
Chong Yidong <cyd@stupidchicken.com>
parents:
98263
diff
changeset
|
451 the changes by repeating the undo command @kbd{C-x u} until you have |
d7df7c98fed8
(File Names): Reorganize description.
Chong Yidong <cyd@stupidchicken.com>
parents:
98263
diff
changeset
|
452 undone all the changes; but reverting is easier.) |
84239 | 453 |
454 @findex set-visited-file-name | |
455 @kbd{M-x set-visited-file-name} alters the name of the file that the | |
456 current buffer is visiting. It reads the new file name using the | |
457 minibuffer. Then it marks the buffer as visiting that file name, and | |
458 changes the buffer name correspondingly. @code{set-visited-file-name} | |
459 does not save the buffer in the newly visited file; it just alters the | |
460 records inside Emacs in case you do save later. It also marks the | |
461 buffer as ``modified'' so that @kbd{C-x C-s} in that buffer | |
462 @emph{will} save. | |
463 | |
464 @kindex C-x C-w | |
465 @findex write-file | |
98636
d7df7c98fed8
(File Names): Reorganize description.
Chong Yidong <cyd@stupidchicken.com>
parents:
98263
diff
changeset
|
466 If you wish to mark the buffer as visiting a different file and save |
d7df7c98fed8
(File Names): Reorganize description.
Chong Yidong <cyd@stupidchicken.com>
parents:
98263
diff
changeset
|
467 it right away, use @kbd{C-x C-w} (@code{write-file}). This is |
d7df7c98fed8
(File Names): Reorganize description.
Chong Yidong <cyd@stupidchicken.com>
parents:
98263
diff
changeset
|
468 equivalent to @code{set-visited-file-name} followed by @kbd{C-x C-s}, |
d7df7c98fed8
(File Names): Reorganize description.
Chong Yidong <cyd@stupidchicken.com>
parents:
98263
diff
changeset
|
469 except that @kbd{C-x C-w} asks for confirmation if the file exists. |
84239 | 470 @kbd{C-x C-s} used on a buffer that is not visiting a file has the |
471 same effect as @kbd{C-x C-w}; that is, it reads a file name, marks the | |
98636
d7df7c98fed8
(File Names): Reorganize description.
Chong Yidong <cyd@stupidchicken.com>
parents:
98263
diff
changeset
|
472 buffer as visiting that file, and saves it there. The default file |
d7df7c98fed8
(File Names): Reorganize description.
Chong Yidong <cyd@stupidchicken.com>
parents:
98263
diff
changeset
|
473 name in a buffer that is not visiting a file is made by combining the |
d7df7c98fed8
(File Names): Reorganize description.
Chong Yidong <cyd@stupidchicken.com>
parents:
98263
diff
changeset
|
474 buffer name with the buffer's default directory (@pxref{File Names}). |
84239 | 475 |
476 If the new file name implies a major mode, then @kbd{C-x C-w} switches | |
477 to that major mode, in most cases. The command | |
478 @code{set-visited-file-name} also does this. @xref{Choosing Modes}. | |
479 | |
480 If Emacs is about to save a file and sees that the date of the latest | |
481 version on disk does not match what Emacs last read or wrote, Emacs | |
482 notifies you of this fact, because it probably indicates a problem caused | |
483 by simultaneous editing and requires your immediate attention. | |
484 @xref{Interlocking,, Simultaneous Editing}. | |
485 | |
486 @node Backup | |
487 @subsection Backup Files | |
488 @cindex backup file | |
489 @vindex make-backup-files | |
490 @vindex vc-make-backup-files | |
491 | |
492 On most operating systems, rewriting a file automatically destroys all | |
493 record of what the file used to contain. Thus, saving a file from Emacs | |
494 throws away the old contents of the file---or it would, except that | |
495 Emacs carefully copies the old contents to another file, called the | |
496 @dfn{backup} file, before actually saving. | |
497 | |
98636
d7df7c98fed8
(File Names): Reorganize description.
Chong Yidong <cyd@stupidchicken.com>
parents:
98263
diff
changeset
|
498 Emacs makes a backup for a file only the first time the file is |
d7df7c98fed8
(File Names): Reorganize description.
Chong Yidong <cyd@stupidchicken.com>
parents:
98263
diff
changeset
|
499 saved from a buffer. No matter how many times you subsequently save |
d7df7c98fed8
(File Names): Reorganize description.
Chong Yidong <cyd@stupidchicken.com>
parents:
98263
diff
changeset
|
500 the file, its backup remains unchanged. However, if you kill the |
d7df7c98fed8
(File Names): Reorganize description.
Chong Yidong <cyd@stupidchicken.com>
parents:
98263
diff
changeset
|
501 buffer and then visit the file again, a new backup file will be made. |
d7df7c98fed8
(File Names): Reorganize description.
Chong Yidong <cyd@stupidchicken.com>
parents:
98263
diff
changeset
|
502 |
84239 | 503 For most files, the variable @code{make-backup-files} determines |
504 whether to make backup files. On most operating systems, its default | |
505 value is @code{t}, so that Emacs does write backup files. | |
506 | |
507 For files managed by a version control system (@pxref{Version | |
508 Control}), the variable @code{vc-make-backup-files} determines whether | |
509 to make backup files. By default it is @code{nil}, since backup files | |
510 are redundant when you store all the previous versions in a version | |
511 control system. | |
512 @iftex | |
513 @xref{General VC Options,,,emacs-xtra, Specialized Emacs Features}. | |
514 @end iftex | |
515 @ifnottex | |
516 @xref{General VC Options}. | |
517 @end ifnottex | |
518 | |
519 At your option, Emacs can keep either a single backup for each file, | |
520 or make a series of numbered backup files for each file that you edit. | |
98636
d7df7c98fed8
(File Names): Reorganize description.
Chong Yidong <cyd@stupidchicken.com>
parents:
98263
diff
changeset
|
521 @xref{Backup Names}. |
84239 | 522 |
523 @vindex backup-enable-predicate | |
524 @vindex temporary-file-directory | |
525 @vindex small-temporary-file-directory | |
526 The default value of the @code{backup-enable-predicate} variable | |
527 prevents backup files being written for files in the directories used | |
528 for temporary files, specified by @code{temporary-file-directory} or | |
529 @code{small-temporary-file-directory}. | |
530 | |
98636
d7df7c98fed8
(File Names): Reorganize description.
Chong Yidong <cyd@stupidchicken.com>
parents:
98263
diff
changeset
|
531 You can explicitly tell Emacs to make another backup file from a |
d7df7c98fed8
(File Names): Reorganize description.
Chong Yidong <cyd@stupidchicken.com>
parents:
98263
diff
changeset
|
532 buffer, even though that buffer has been saved before. If you save |
84239 | 533 the buffer with @kbd{C-u C-x C-s}, the version thus saved will be made |
98636
d7df7c98fed8
(File Names): Reorganize description.
Chong Yidong <cyd@stupidchicken.com>
parents:
98263
diff
changeset
|
534 into a backup file if you save the buffer again. @kbd{C-u C-u C-x |
d7df7c98fed8
(File Names): Reorganize description.
Chong Yidong <cyd@stupidchicken.com>
parents:
98263
diff
changeset
|
535 C-s} saves the buffer, but first makes the previous file contents into |
d7df7c98fed8
(File Names): Reorganize description.
Chong Yidong <cyd@stupidchicken.com>
parents:
98263
diff
changeset
|
536 a new backup file. @kbd{C-u C-u C-u C-x C-s} does both things: it |
d7df7c98fed8
(File Names): Reorganize description.
Chong Yidong <cyd@stupidchicken.com>
parents:
98263
diff
changeset
|
537 makes a backup from the previous contents, and arranges to make |
d7df7c98fed8
(File Names): Reorganize description.
Chong Yidong <cyd@stupidchicken.com>
parents:
98263
diff
changeset
|
538 another from the newly saved contents if you save again. |
84239 | 539 |
540 @menu | |
541 * Names: Backup Names. How backup files are named. | |
542 * Deletion: Backup Deletion. Emacs deletes excess numbered backups. | |
543 * Copying: Backup Copying. Backups can be made by copying or renaming. | |
544 @end menu | |
545 | |
98636
d7df7c98fed8
(File Names): Reorganize description.
Chong Yidong <cyd@stupidchicken.com>
parents:
98263
diff
changeset
|
546 @node Backup Names |
d7df7c98fed8
(File Names): Reorganize description.
Chong Yidong <cyd@stupidchicken.com>
parents:
98263
diff
changeset
|
547 @subsubsection Single or Numbered Backups |
d7df7c98fed8
(File Names): Reorganize description.
Chong Yidong <cyd@stupidchicken.com>
parents:
98263
diff
changeset
|
548 |
d7df7c98fed8
(File Names): Reorganize description.
Chong Yidong <cyd@stupidchicken.com>
parents:
98263
diff
changeset
|
549 When Emacs makes a backup file, its name is normally constructed by |
d7df7c98fed8
(File Names): Reorganize description.
Chong Yidong <cyd@stupidchicken.com>
parents:
98263
diff
changeset
|
550 appending @samp{~} to the file name being edited; thus, the backup |
d7df7c98fed8
(File Names): Reorganize description.
Chong Yidong <cyd@stupidchicken.com>
parents:
98263
diff
changeset
|
551 file for @file{eval.c} would be @file{eval.c~}. |
d7df7c98fed8
(File Names): Reorganize description.
Chong Yidong <cyd@stupidchicken.com>
parents:
98263
diff
changeset
|
552 |
d7df7c98fed8
(File Names): Reorganize description.
Chong Yidong <cyd@stupidchicken.com>
parents:
98263
diff
changeset
|
553 If access control stops Emacs from writing backup files under the usual |
d7df7c98fed8
(File Names): Reorganize description.
Chong Yidong <cyd@stupidchicken.com>
parents:
98263
diff
changeset
|
554 names, it writes the backup file as @file{%backup%~} in your home |
d7df7c98fed8
(File Names): Reorganize description.
Chong Yidong <cyd@stupidchicken.com>
parents:
98263
diff
changeset
|
555 directory. Only one such file can exist, so only the most recently |
d7df7c98fed8
(File Names): Reorganize description.
Chong Yidong <cyd@stupidchicken.com>
parents:
98263
diff
changeset
|
556 made such backup is available. |
d7df7c98fed8
(File Names): Reorganize description.
Chong Yidong <cyd@stupidchicken.com>
parents:
98263
diff
changeset
|
557 |
d7df7c98fed8
(File Names): Reorganize description.
Chong Yidong <cyd@stupidchicken.com>
parents:
98263
diff
changeset
|
558 Emacs can also make @dfn{numbered backup files}. Numbered backup |
d7df7c98fed8
(File Names): Reorganize description.
Chong Yidong <cyd@stupidchicken.com>
parents:
98263
diff
changeset
|
559 file names contain @samp{.~}, the number, and another @samp{~} after |
d7df7c98fed8
(File Names): Reorganize description.
Chong Yidong <cyd@stupidchicken.com>
parents:
98263
diff
changeset
|
560 the original file name. Thus, the backup files of @file{eval.c} would |
d7df7c98fed8
(File Names): Reorganize description.
Chong Yidong <cyd@stupidchicken.com>
parents:
98263
diff
changeset
|
561 be called @file{eval.c.~1~}, @file{eval.c.~2~}, and so on, all the way |
d7df7c98fed8
(File Names): Reorganize description.
Chong Yidong <cyd@stupidchicken.com>
parents:
98263
diff
changeset
|
562 through names like @file{eval.c.~259~} and beyond. |
84239 | 563 |
564 @vindex version-control | |
98636
d7df7c98fed8
(File Names): Reorganize description.
Chong Yidong <cyd@stupidchicken.com>
parents:
98263
diff
changeset
|
565 The variable @code{version-control} determines whether to make |
d7df7c98fed8
(File Names): Reorganize description.
Chong Yidong <cyd@stupidchicken.com>
parents:
98263
diff
changeset
|
566 single backup files or multiple numbered backup files. Its possible |
84239 | 567 values are: |
568 | |
569 @table @code | |
98636
d7df7c98fed8
(File Names): Reorganize description.
Chong Yidong <cyd@stupidchicken.com>
parents:
98263
diff
changeset
|
570 @item nil |
d7df7c98fed8
(File Names): Reorganize description.
Chong Yidong <cyd@stupidchicken.com>
parents:
98263
diff
changeset
|
571 Make numbered backups for files that have numbered backups already. |
d7df7c98fed8
(File Names): Reorganize description.
Chong Yidong <cyd@stupidchicken.com>
parents:
98263
diff
changeset
|
572 Otherwise, make single backups. This is the default. |
84239 | 573 @item t |
574 Make numbered backups. | |
575 @item never | |
576 Never make numbered backups; always make single backups. | |
577 @end table | |
578 | |
579 @noindent | |
580 The usual way to set this variable is globally, through your | |
581 @file{.emacs} file or the customization buffer. However, you can set | |
582 @code{version-control} locally in an individual buffer to control the | |
98261
cd0af9d51c4b
Jim Blandy <jimb at red-bean.com>
Glenn Morris <rgm@gnu.org>
parents:
97358
diff
changeset
|
583 making of backups for that buffer's file (@pxref{Locals}). You can |
cd0af9d51c4b
Jim Blandy <jimb at red-bean.com>
Glenn Morris <rgm@gnu.org>
parents:
97358
diff
changeset
|
584 have Emacs set @code{version-control} locally whenever you visit a |
98263
c3f5f1ee7fb8
(Numbered Backups): Mention that some modes set version-control.
Glenn Morris <rgm@gnu.org>
parents:
98261
diff
changeset
|
585 given file (@pxref{File Variables}). Some modes, such as Rmail mode, |
c3f5f1ee7fb8
(Numbered Backups): Mention that some modes set version-control.
Glenn Morris <rgm@gnu.org>
parents:
98261
diff
changeset
|
586 set this variable. |
84239 | 587 |
588 @cindex @env{VERSION_CONTROL} environment variable | |
589 If you set the environment variable @env{VERSION_CONTROL}, to tell | |
590 various GNU utilities what to do with backup files, Emacs also obeys the | |
591 environment variable by setting the Lisp variable @code{version-control} | |
592 accordingly at startup. If the environment variable's value is @samp{t} | |
593 or @samp{numbered}, then @code{version-control} becomes @code{t}; if the | |
594 value is @samp{nil} or @samp{existing}, then @code{version-control} | |
595 becomes @code{nil}; if it is @samp{never} or @samp{simple}, then | |
596 @code{version-control} becomes @code{never}. | |
597 | |
98636
d7df7c98fed8
(File Names): Reorganize description.
Chong Yidong <cyd@stupidchicken.com>
parents:
98263
diff
changeset
|
598 @vindex backup-directory-alist |
d7df7c98fed8
(File Names): Reorganize description.
Chong Yidong <cyd@stupidchicken.com>
parents:
98263
diff
changeset
|
599 You can customize the variable @code{backup-directory-alist} to |
d7df7c98fed8
(File Names): Reorganize description.
Chong Yidong <cyd@stupidchicken.com>
parents:
98263
diff
changeset
|
600 specify that files matching certain patterns should be backed up in |
d7df7c98fed8
(File Names): Reorganize description.
Chong Yidong <cyd@stupidchicken.com>
parents:
98263
diff
changeset
|
601 specific directories. This variable applies to both single and |
d7df7c98fed8
(File Names): Reorganize description.
Chong Yidong <cyd@stupidchicken.com>
parents:
98263
diff
changeset
|
602 numbered backups. A typical use is to add an element @code{("." |
d7df7c98fed8
(File Names): Reorganize description.
Chong Yidong <cyd@stupidchicken.com>
parents:
98263
diff
changeset
|
603 . @var{dir})} to make all backups in the directory with absolute name |
d7df7c98fed8
(File Names): Reorganize description.
Chong Yidong <cyd@stupidchicken.com>
parents:
98263
diff
changeset
|
604 @var{dir}; Emacs modifies the backup file names to avoid clashes |
d7df7c98fed8
(File Names): Reorganize description.
Chong Yidong <cyd@stupidchicken.com>
parents:
98263
diff
changeset
|
605 between files with the same names originating in different |
d7df7c98fed8
(File Names): Reorganize description.
Chong Yidong <cyd@stupidchicken.com>
parents:
98263
diff
changeset
|
606 directories. Alternatively, adding, @code{("." . ".~")} would make |
d7df7c98fed8
(File Names): Reorganize description.
Chong Yidong <cyd@stupidchicken.com>
parents:
98263
diff
changeset
|
607 backups in the invisible subdirectory @file{.~} of the original file's |
d7df7c98fed8
(File Names): Reorganize description.
Chong Yidong <cyd@stupidchicken.com>
parents:
98263
diff
changeset
|
608 directory. Emacs creates the directory, if necessary, to make the |
d7df7c98fed8
(File Names): Reorganize description.
Chong Yidong <cyd@stupidchicken.com>
parents:
98263
diff
changeset
|
609 backup. |
84239 | 610 |
611 @vindex make-backup-file-name-function | |
98636
d7df7c98fed8
(File Names): Reorganize description.
Chong Yidong <cyd@stupidchicken.com>
parents:
98263
diff
changeset
|
612 If you define the variable @code{make-backup-file-name-function} to |
d7df7c98fed8
(File Names): Reorganize description.
Chong Yidong <cyd@stupidchicken.com>
parents:
98263
diff
changeset
|
613 a suitable Lisp function, that overrides the usual way Emacs |
d7df7c98fed8
(File Names): Reorganize description.
Chong Yidong <cyd@stupidchicken.com>
parents:
98263
diff
changeset
|
614 constructs backup file names. |
84239 | 615 |
616 @node Backup Deletion | |
617 @subsubsection Automatic Deletion of Backups | |
618 | |
619 To prevent excessive consumption of disk space, Emacs can delete numbered | |
620 backup versions automatically. Generally Emacs keeps the first few backups | |
621 and the latest few backups, deleting any in between. This happens every | |
622 time a new backup is made. | |
623 | |
624 @vindex kept-old-versions | |
625 @vindex kept-new-versions | |
626 The two variables @code{kept-old-versions} and | |
627 @code{kept-new-versions} control this deletion. Their values are, | |
628 respectively, the number of oldest (lowest-numbered) backups to keep | |
629 and the number of newest (highest-numbered) ones to keep, each time a | |
630 new backup is made. The backups in the middle (excluding those oldest | |
631 and newest) are the excess middle versions---those backups are | |
632 deleted. These variables' values are used when it is time to delete | |
633 excess versions, just after a new backup version is made; the newly | |
634 made backup is included in the count in @code{kept-new-versions}. By | |
635 default, both variables are 2. | |
636 | |
637 @vindex delete-old-versions | |
638 If @code{delete-old-versions} is @code{t}, Emacs deletes the excess | |
639 backup files silently. If it is @code{nil}, the default, Emacs asks | |
640 you whether it should delete the excess backup versions. If it has | |
641 any other value, then Emacs never automatically deletes backups. | |
642 | |
643 Dired's @kbd{.} (Period) command can also be used to delete old versions. | |
644 @xref{Dired Deletion}. | |
645 | |
646 @node Backup Copying | |
647 @subsubsection Copying vs.@: Renaming | |
648 | |
649 Backup files can be made by copying the old file or by renaming it. | |
650 This makes a difference when the old file has multiple names (hard | |
651 links). If the old file is renamed into the backup file, then the | |
652 alternate names become names for the backup file. If the old file is | |
653 copied instead, then the alternate names remain names for the file | |
654 that you are editing, and the contents accessed by those names will be | |
655 the new contents. | |
656 | |
657 The method of making a backup file may also affect the file's owner | |
658 and group. If copying is used, these do not change. If renaming is used, | |
659 you become the file's owner, and the file's group becomes the default | |
660 (different operating systems have different defaults for the group). | |
661 | |
662 Having the owner change is usually a good idea, because then the owner | |
663 always shows who last edited the file. Also, the owners of the backups | |
664 show who produced those versions. Occasionally there is a file whose | |
665 owner should not change; it is a good idea for such files to contain | |
666 local variable lists to set @code{backup-by-copying-when-mismatch} | |
667 locally (@pxref{File Variables}). | |
668 | |
669 @vindex backup-by-copying | |
670 @vindex backup-by-copying-when-linked | |
671 @vindex backup-by-copying-when-mismatch | |
672 @vindex backup-by-copying-when-privileged-mismatch | |
673 @cindex file ownership, and backup | |
674 @cindex backup, and user-id | |
675 The choice of renaming or copying is controlled by four variables. | |
676 Renaming is the default choice. If the variable | |
677 @code{backup-by-copying} is non-@code{nil}, copying is used. Otherwise, | |
678 if the variable @code{backup-by-copying-when-linked} is non-@code{nil}, | |
679 then copying is used for files that have multiple names, but renaming | |
680 may still be used when the file being edited has only one name. If the | |
681 variable @code{backup-by-copying-when-mismatch} is non-@code{nil}, then | |
682 copying is used if renaming would cause the file's owner or group to | |
683 change. @code{backup-by-copying-when-mismatch} is @code{t} by default | |
684 if you start Emacs as the superuser. The fourth variable, | |
685 @code{backup-by-copying-when-privileged-mismatch}, gives the highest | |
686 numeric user-id for which @code{backup-by-copying-when-mismatch} will be | |
687 forced on. This is useful when low-numbered user-ids are assigned to | |
688 special system users, such as @code{root}, @code{bin}, @code{daemon}, | |
689 etc., which must maintain ownership of files. | |
690 | |
691 When a file is managed with a version control system (@pxref{Version | |
692 Control}), Emacs does not normally make backups in the usual way for | |
693 that file. But check-in and check-out are similar in some ways to | |
694 making backups. One unfortunate similarity is that these operations | |
695 typically break hard links, disconnecting the file name you visited from | |
696 any alternate names for the same file. This has nothing to do with | |
697 Emacs---the version control system does it. | |
698 | |
699 @node Customize Save | |
700 @subsection Customizing Saving of Files | |
701 | |
702 @vindex require-final-newline | |
703 If the value of the variable @code{require-final-newline} is | |
704 @code{t}, saving or writing a file silently puts a newline at the end | |
705 if there isn't already one there. If the value is @code{visit}, Emacs | |
706 adds a newline at the end of any file that doesn't have one, just | |
707 after it visits the file. (This marks the buffer as modified, and you | |
708 can undo it.) If the value is @code{visit-save}, that means to add | |
709 newlines both on visiting and on saving. If the value is @code{nil}, | |
710 Emacs leaves the end of the file unchanged; if it's neither @code{nil} | |
711 nor @code{t}, Emacs asks you whether to add a newline. The default is | |
712 @code{nil}. | |
713 | |
714 @vindex mode-require-final-newline | |
715 Many major modes are designed for specific kinds of files that are | |
716 always supposed to end in newlines. These major modes set the | |
717 variable @code{require-final-newline} according to | |
718 @code{mode-require-final-newline}. By setting the latter variable, | |
719 you can control how these modes handle final newlines. | |
720 | |
721 @vindex write-region-inhibit-fsync | |
722 When Emacs saves a file, it invokes the @code{fsync} system call to | |
723 force the data immediately out to disk. This is important for safety | |
724 if the system crashes or in case of power outage. However, it can be | |
725 disruptive on laptops using power saving, because it requires the disk | |
726 to spin up each time you save a file. Setting | |
727 @code{write-region-inhibit-fsync} to a non-@code{nil} value disables | |
728 this synchronization. Be careful---this means increased risk of data | |
729 loss. | |
730 | |
731 @node Interlocking | |
732 @subsection Protection against Simultaneous Editing | |
733 | |
734 @cindex file dates | |
735 @cindex simultaneous editing | |
736 Simultaneous editing occurs when two users visit the same file, both | |
737 make changes, and then both save them. If nobody were informed that | |
738 this was happening, whichever user saved first would later find that his | |
739 changes were lost. | |
740 | |
741 On some systems, Emacs notices immediately when the second user starts | |
742 to change the file, and issues an immediate warning. On all systems, | |
743 Emacs checks when you save the file, and warns if you are about to | |
744 overwrite another user's changes. You can prevent loss of the other | |
745 user's work by taking the proper corrective action instead of saving the | |
746 file. | |
747 | |
748 @findex ask-user-about-lock | |
749 @cindex locking files | |
750 When you make the first modification in an Emacs buffer that is | |
751 visiting a file, Emacs records that the file is @dfn{locked} by you. | |
98636
d7df7c98fed8
(File Names): Reorganize description.
Chong Yidong <cyd@stupidchicken.com>
parents:
98263
diff
changeset
|
752 (It does this by creating a specially-named symbolic link in the same |
d7df7c98fed8
(File Names): Reorganize description.
Chong Yidong <cyd@stupidchicken.com>
parents:
98263
diff
changeset
|
753 directory.) Emacs removes the lock when you save the changes. The |
d7df7c98fed8
(File Names): Reorganize description.
Chong Yidong <cyd@stupidchicken.com>
parents:
98263
diff
changeset
|
754 idea is that the file is locked whenever an Emacs buffer visiting it |
d7df7c98fed8
(File Names): Reorganize description.
Chong Yidong <cyd@stupidchicken.com>
parents:
98263
diff
changeset
|
755 has unsaved changes. |
84239 | 756 |
757 @cindex collision | |
758 If you begin to modify the buffer while the visited file is locked by | |
759 someone else, this constitutes a @dfn{collision}. When Emacs detects a | |
760 collision, it asks you what to do, by calling the Lisp function | |
761 @code{ask-user-about-lock}. You can redefine this function for the sake | |
762 of customization. The standard definition of this function asks you a | |
763 question and accepts three possible answers: | |
764 | |
765 @table @kbd | |
766 @item s | |
767 Steal the lock. Whoever was already changing the file loses the lock, | |
768 and you gain the lock. | |
769 @item p | |
770 Proceed. Go ahead and edit the file despite its being locked by someone else. | |
771 @item q | |
772 Quit. This causes an error (@code{file-locked}), and the buffer | |
773 contents remain unchanged---the modification you were trying to make | |
774 does not actually take place. | |
775 @end table | |
776 | |
777 Note that locking works on the basis of a file name; if a file has | |
778 multiple names, Emacs does not realize that the two names are the same file | |
779 and cannot prevent two users from editing it simultaneously under different | |
780 names. However, basing locking on names means that Emacs can interlock the | |
781 editing of new files that will not really exist until they are saved. | |
782 | |
783 Some systems are not configured to allow Emacs to make locks, and | |
784 there are cases where lock files cannot be written. In these cases, | |
785 Emacs cannot detect trouble in advance, but it still can detect the | |
786 collision when you try to save a file and overwrite someone else's | |
98636
d7df7c98fed8
(File Names): Reorganize description.
Chong Yidong <cyd@stupidchicken.com>
parents:
98263
diff
changeset
|
787 changes. Every time Emacs saves a buffer, it first checks the |
d7df7c98fed8
(File Names): Reorganize description.
Chong Yidong <cyd@stupidchicken.com>
parents:
98263
diff
changeset
|
788 last-modification date of the existing file on disk to verify that it |
d7df7c98fed8
(File Names): Reorganize description.
Chong Yidong <cyd@stupidchicken.com>
parents:
98263
diff
changeset
|
789 has not changed since the file was last visited or saved. If the date |
d7df7c98fed8
(File Names): Reorganize description.
Chong Yidong <cyd@stupidchicken.com>
parents:
98263
diff
changeset
|
790 does not match, it implies that changes were made in the file in some |
d7df7c98fed8
(File Names): Reorganize description.
Chong Yidong <cyd@stupidchicken.com>
parents:
98263
diff
changeset
|
791 other way, and these changes are about to be lost if Emacs actually |
d7df7c98fed8
(File Names): Reorganize description.
Chong Yidong <cyd@stupidchicken.com>
parents:
98263
diff
changeset
|
792 does save. To prevent this, Emacs displays a warning message and asks |
d7df7c98fed8
(File Names): Reorganize description.
Chong Yidong <cyd@stupidchicken.com>
parents:
98263
diff
changeset
|
793 for confirmation before saving. Occasionally you will know why the |
d7df7c98fed8
(File Names): Reorganize description.
Chong Yidong <cyd@stupidchicken.com>
parents:
98263
diff
changeset
|
794 file was changed and know that it does not matter; then you can answer |
d7df7c98fed8
(File Names): Reorganize description.
Chong Yidong <cyd@stupidchicken.com>
parents:
98263
diff
changeset
|
795 @kbd{yes} and proceed. Otherwise, you should cancel the save with |
d7df7c98fed8
(File Names): Reorganize description.
Chong Yidong <cyd@stupidchicken.com>
parents:
98263
diff
changeset
|
796 @kbd{C-g} and investigate the situation. |
84239 | 797 |
798 If Emacs or the operating system crashes, this may leave behind lock | |
799 files which are stale, so you may occasionally get warnings about | |
800 spurious collisions. When you determine that the collision is spurious, | |
801 just use @kbd{p} to tell Emacs to go ahead anyway. | |
802 | |
803 The first thing you should do when notified that simultaneous editing | |
804 has already taken place is to list the directory with @kbd{C-u C-x C-d} | |
805 (@pxref{Directories}). This shows the file's current author. You | |
806 should attempt to contact him to warn him not to continue editing. | |
807 Often the next step is to save the contents of your Emacs buffer under a | |
808 different name, and use @code{diff} to compare the two files.@refill | |
809 | |
810 @node File Shadowing | |
811 @subsection Shadowing Files | |
812 @cindex shadow files | |
813 @cindex file shadows | |
814 @findex shadow-initialize | |
815 | |
816 @table @kbd | |
817 @item M-x shadow-initialize | |
818 Set up file shadowing. | |
819 @item M-x shadow-define-literal-group | |
820 Declare a single file to be shared between sites. | |
821 @item M-x shadow-define-regexp-group | |
822 Make all files that match each of a group of files be shared between hosts. | |
823 @item M-x shadow-define-cluster @key{RET} @var{name} @key{RET} | |
824 Define a shadow file cluster @var{name}. | |
825 @item M-x shadow-copy-files | |
826 Copy all pending shadow files. | |
827 @item M-x shadow-cancel | |
828 Cancel the instruction to shadow some files. | |
829 @end table | |
830 | |
831 You can arrange to keep identical @dfn{shadow} copies of certain files | |
832 in more than one place---possibly on different machines. To do this, | |
833 first you must set up a @dfn{shadow file group}, which is a set of | |
834 identically-named files shared between a list of sites. The file | |
835 group is permanent and applies to further Emacs sessions as well as | |
836 the current one. Once the group is set up, every time you exit Emacs, | |
837 it will copy the file you edited to the other files in its group. You | |
838 can also do the copying without exiting Emacs, by typing @kbd{M-x | |
839 shadow-copy-files}. | |
840 | |
841 To set up a shadow file group, use @kbd{M-x | |
842 shadow-define-literal-group} or @kbd{M-x shadow-define-regexp-group}. | |
843 See their documentation strings for further information. | |
844 | |
845 Before copying a file to its shadows, Emacs asks for confirmation. | |
846 You can answer ``no'' to bypass copying of this file, this time. If | |
847 you want to cancel the shadowing permanently for a certain file, use | |
848 @kbd{M-x shadow-cancel} to eliminate or change the shadow file group. | |
849 | |
850 A @dfn{shadow cluster} is a group of hosts that share directories, so | |
851 that copying to or from one of them is sufficient to update the file | |
852 on all of them. Each shadow cluster has a name, and specifies the | |
853 network address of a primary host (the one we copy files to), and a | |
854 regular expression that matches the host names of all the other hosts | |
855 in the cluster. You can define a shadow cluster with @kbd{M-x | |
856 shadow-define-cluster}. | |
857 | |
858 @node Time Stamps | |
859 @subsection Updating Time Stamps Automatically | |
860 @cindex time stamps | |
861 @cindex modification dates | |
862 @cindex locale, date format | |
863 | |
864 You can arrange to put a time stamp in a file, so that it will be updated | |
865 automatically each time you edit and save the file. The time stamp | |
866 has to be in the first eight lines of the file, and you should | |
867 insert it like this: | |
868 | |
869 @example | |
870 Time-stamp: <> | |
871 @end example | |
872 | |
873 @noindent | |
874 or like this: | |
875 | |
876 @example | |
877 Time-stamp: " " | |
878 @end example | |
879 | |
880 @findex time-stamp | |
881 Then add the hook function @code{time-stamp} to the hook | |
882 @code{before-save-hook}; that hook function will automatically update | |
883 the time stamp, inserting the current date and time when you save the | |
884 file. You can also use the command @kbd{M-x time-stamp} to update the | |
885 time stamp manually. For other customizations, see the Custom group | |
886 @code{time-stamp}. Note that non-numeric fields in the time stamp are | |
887 formatted according to your locale setting (@pxref{Environment}). | |
888 | |
889 @node Reverting | |
890 @section Reverting a Buffer | |
891 @findex revert-buffer | |
892 @cindex drastic changes | |
893 @cindex reread a file | |
894 | |
895 If you have made extensive changes to a file and then change your mind | |
896 about them, you can get rid of them by reading in the previous version | |
897 of the file. To do this, use @kbd{M-x revert-buffer}, which operates on | |
898 the current buffer. Since reverting a buffer unintentionally could lose | |
899 a lot of work, you must confirm this command with @kbd{yes}. | |
900 | |
901 @code{revert-buffer} tries to position point in such a way that, if | |
902 the file was edited only slightly, you will be at approximately the | |
903 same piece of text after reverting as before. However, if you have made | |
904 drastic changes, point may wind up in a totally different piece of text. | |
905 | |
98636
d7df7c98fed8
(File Names): Reorganize description.
Chong Yidong <cyd@stupidchicken.com>
parents:
98263
diff
changeset
|
906 Reverting marks the buffer as ``not modified''. |
d7df7c98fed8
(File Names): Reorganize description.
Chong Yidong <cyd@stupidchicken.com>
parents:
98263
diff
changeset
|
907 |
d7df7c98fed8
(File Names): Reorganize description.
Chong Yidong <cyd@stupidchicken.com>
parents:
98263
diff
changeset
|
908 Some kinds of buffers that are not associated with files, such as |
d7df7c98fed8
(File Names): Reorganize description.
Chong Yidong <cyd@stupidchicken.com>
parents:
98263
diff
changeset
|
909 Dired buffers, can also be reverted. For them, reverting means |
d7df7c98fed8
(File Names): Reorganize description.
Chong Yidong <cyd@stupidchicken.com>
parents:
98263
diff
changeset
|
910 recalculating their contents. Buffers created explicitly with |
d7df7c98fed8
(File Names): Reorganize description.
Chong Yidong <cyd@stupidchicken.com>
parents:
98263
diff
changeset
|
911 @kbd{C-x b} cannot be reverted; @code{revert-buffer} reports an error |
d7df7c98fed8
(File Names): Reorganize description.
Chong Yidong <cyd@stupidchicken.com>
parents:
98263
diff
changeset
|
912 if you try. |
84239 | 913 |
914 @vindex revert-without-query | |
915 When you edit a file that changes automatically and frequently---for | |
98636
d7df7c98fed8
(File Names): Reorganize description.
Chong Yidong <cyd@stupidchicken.com>
parents:
98263
diff
changeset
|
916 example, a log of output from a process that continues to run---it may |
d7df7c98fed8
(File Names): Reorganize description.
Chong Yidong <cyd@stupidchicken.com>
parents:
98263
diff
changeset
|
917 be useful for Emacs to revert the file without querying you. To |
d7df7c98fed8
(File Names): Reorganize description.
Chong Yidong <cyd@stupidchicken.com>
parents:
98263
diff
changeset
|
918 request this behavior, set the variable @code{revert-without-query} to |
d7df7c98fed8
(File Names): Reorganize description.
Chong Yidong <cyd@stupidchicken.com>
parents:
98263
diff
changeset
|
919 a list of regular expressions. When a file name matches one of these |
84239 | 920 regular expressions, @code{find-file} and @code{revert-buffer} will |
921 revert it automatically if it has changed---provided the buffer itself | |
922 is not modified. (If you have edited the text, it would be wrong to | |
923 discard your changes.) | |
924 | |
925 @cindex Global Auto-Revert mode | |
926 @cindex mode, Global Auto-Revert | |
927 @cindex Auto-Revert mode | |
928 @cindex mode, Auto-Revert | |
929 @findex global-auto-revert-mode | |
930 @findex auto-revert-mode | |
931 @findex auto-revert-tail-mode | |
98636
d7df7c98fed8
(File Names): Reorganize description.
Chong Yidong <cyd@stupidchicken.com>
parents:
98263
diff
changeset
|
932 @vindex auto-revert-interval |
d7df7c98fed8
(File Names): Reorganize description.
Chong Yidong <cyd@stupidchicken.com>
parents:
98263
diff
changeset
|
933 |
d7df7c98fed8
(File Names): Reorganize description.
Chong Yidong <cyd@stupidchicken.com>
parents:
98263
diff
changeset
|
934 In addition, you can tell Emacs to periodically revert a buffer by |
d7df7c98fed8
(File Names): Reorganize description.
Chong Yidong <cyd@stupidchicken.com>
parents:
98263
diff
changeset
|
935 typing @kbd{M-x auto-revert-mode}. This turns on Auto-Revert mode, a |
d7df7c98fed8
(File Names): Reorganize description.
Chong Yidong <cyd@stupidchicken.com>
parents:
98263
diff
changeset
|
936 minor mode that makes Emacs automatically revert the current buffer |
d7df7c98fed8
(File Names): Reorganize description.
Chong Yidong <cyd@stupidchicken.com>
parents:
98263
diff
changeset
|
937 every five seconds. You can change this interval through the variable |
d7df7c98fed8
(File Names): Reorganize description.
Chong Yidong <cyd@stupidchicken.com>
parents:
98263
diff
changeset
|
938 @code{auto-revert-interval}. Typing @kbd{M-x global-auto-revert-mode} |
d7df7c98fed8
(File Names): Reorganize description.
Chong Yidong <cyd@stupidchicken.com>
parents:
98263
diff
changeset
|
939 enables Global Auto-Revert mode, which does the same for all file |
d7df7c98fed8
(File Names): Reorganize description.
Chong Yidong <cyd@stupidchicken.com>
parents:
98263
diff
changeset
|
940 buffers. Auto-Revert mode and Global Auto-Revert modes do not check |
d7df7c98fed8
(File Names): Reorganize description.
Chong Yidong <cyd@stupidchicken.com>
parents:
98263
diff
changeset
|
941 or revert remote files, because that is usually too slow. |
d7df7c98fed8
(File Names): Reorganize description.
Chong Yidong <cyd@stupidchicken.com>
parents:
98263
diff
changeset
|
942 |
d7df7c98fed8
(File Names): Reorganize description.
Chong Yidong <cyd@stupidchicken.com>
parents:
98263
diff
changeset
|
943 One use of Auto-Revert mode is to ``tail'' a file such as a system |
84239 | 944 log, so that changes made to that file by other programs are |
945 continuously displayed. To do this, just move the point to the end of | |
946 the buffer, and it will stay there as the file contents change. | |
947 However, if you are sure that the file will only change by growing at | |
948 the end, use Auto-Revert Tail mode instead | |
949 (@code{auto-revert-tail-mode}). It is more efficient for this. | |
950 | |
951 @xref{VC Mode Line}, for Auto Revert peculiarities in buffers that | |
952 visit files under version control. | |
953 | |
954 @ifnottex | |
955 @include arevert-xtra.texi | |
956 @end ifnottex | |
957 | |
958 @node Auto Save | |
959 @section Auto-Saving: Protection Against Disasters | |
960 @cindex Auto Save mode | |
961 @cindex mode, Auto Save | |
962 @cindex crashes | |
963 | |
98636
d7df7c98fed8
(File Names): Reorganize description.
Chong Yidong <cyd@stupidchicken.com>
parents:
98263
diff
changeset
|
964 From time to time, Emacs automatically saves each visited file in a |
d7df7c98fed8
(File Names): Reorganize description.
Chong Yidong <cyd@stupidchicken.com>
parents:
98263
diff
changeset
|
965 separate file, without altering the file you actually use. This is |
d7df7c98fed8
(File Names): Reorganize description.
Chong Yidong <cyd@stupidchicken.com>
parents:
98263
diff
changeset
|
966 called @dfn{auto-saving}. It prevents you from losing more than a |
d7df7c98fed8
(File Names): Reorganize description.
Chong Yidong <cyd@stupidchicken.com>
parents:
98263
diff
changeset
|
967 limited amount of work if the system crashes. |
84239 | 968 |
969 When Emacs determines that it is time for auto-saving, it considers | |
970 each buffer, and each is auto-saved if auto-saving is enabled for it | |
971 and it has been changed since the last time it was auto-saved. The | |
972 message @samp{Auto-saving...} is displayed in the echo area during | |
973 auto-saving, if any files are actually auto-saved. Errors occurring | |
974 during auto-saving are caught so that they do not interfere with the | |
975 execution of commands you have been typing. | |
976 | |
977 @menu | |
978 * Files: Auto Save Files. The file where auto-saved changes are | |
979 actually made until you save the file. | |
980 * Control: Auto Save Control. Controlling when and how often to auto-save. | |
981 * Recover:: Recovering text from auto-save files. | |
982 @end menu | |
983 | |
984 @node Auto Save Files | |
985 @subsection Auto-Save Files | |
986 | |
98636
d7df7c98fed8
(File Names): Reorganize description.
Chong Yidong <cyd@stupidchicken.com>
parents:
98263
diff
changeset
|
987 Auto-saving does not normally save in the files that you visited, |
d7df7c98fed8
(File Names): Reorganize description.
Chong Yidong <cyd@stupidchicken.com>
parents:
98263
diff
changeset
|
988 because it can be very undesirable to save a change that you did not |
d7df7c98fed8
(File Names): Reorganize description.
Chong Yidong <cyd@stupidchicken.com>
parents:
98263
diff
changeset
|
989 want to make permanent. Instead, auto-saving is done in a different |
d7df7c98fed8
(File Names): Reorganize description.
Chong Yidong <cyd@stupidchicken.com>
parents:
98263
diff
changeset
|
990 file called the @dfn{auto-save file}, and the visited file is changed |
d7df7c98fed8
(File Names): Reorganize description.
Chong Yidong <cyd@stupidchicken.com>
parents:
98263
diff
changeset
|
991 only when you request saving explicitly (such as with @kbd{C-x C-s}). |
84239 | 992 |
993 Normally, the auto-save file name is made by appending @samp{#} to the | |
994 front and rear of the visited file name. Thus, a buffer visiting file | |
995 @file{foo.c} is auto-saved in a file @file{#foo.c#}. Most buffers that | |
996 are not visiting files are auto-saved only if you request it explicitly; | |
997 when they are auto-saved, the auto-save file name is made by appending | |
998 @samp{#} to the front and rear of buffer name, then | |
999 adding digits and letters at the end for uniqueness. For | |
1000 example, the @samp{*mail*} buffer in which you compose messages to be | |
1001 sent might be auto-saved in a file named @file{#*mail*#704juu}. Auto-save file | |
1002 names are made this way unless you reprogram parts of Emacs to do | |
1003 something different (the functions @code{make-auto-save-file-name} and | |
1004 @code{auto-save-file-name-p}). The file name to be used for auto-saving | |
1005 in a buffer is calculated when auto-saving is turned on in that buffer. | |
1006 | |
1007 @cindex auto-save for remote files | |
1008 @vindex auto-save-file-name-transforms | |
1009 The variable @code{auto-save-file-name-transforms} allows a degree | |
1010 of control over the auto-save file name. It lets you specify a series | |
1011 of regular expressions and replacements to transform the auto save | |
1012 file name. The default value puts the auto-save files for remote | |
1013 files (@pxref{Remote Files}) into the temporary file directory on the | |
1014 local machine. | |
1015 | |
1016 When you delete a substantial part of the text in a large buffer, auto | |
1017 save turns off temporarily in that buffer. This is because if you | |
1018 deleted the text unintentionally, you might find the auto-save file more | |
1019 useful if it contains the deleted text. To reenable auto-saving after | |
1020 this happens, save the buffer with @kbd{C-x C-s}, or use @kbd{C-u 1 M-x | |
1021 auto-save-mode}. | |
1022 | |
1023 @vindex auto-save-visited-file-name | |
1024 If you want auto-saving to be done in the visited file rather than | |
1025 in a separate auto-save file, set the variable | |
1026 @code{auto-save-visited-file-name} to a non-@code{nil} value. In this | |
1027 mode, there is no real difference between auto-saving and explicit | |
1028 saving. | |
1029 | |
1030 @vindex delete-auto-save-files | |
1031 A buffer's auto-save file is deleted when you save the buffer in its | |
1032 visited file. (You can inhibit this by setting the variable | |
1033 @code{delete-auto-save-files} to @code{nil}.) Changing the visited | |
1034 file name with @kbd{C-x C-w} or @code{set-visited-file-name} renames | |
1035 any auto-save file to go with the new visited name. | |
1036 | |
1037 @node Auto Save Control | |
1038 @subsection Controlling Auto-Saving | |
1039 | |
1040 @vindex auto-save-default | |
1041 @findex auto-save-mode | |
1042 Each time you visit a file, auto-saving is turned on for that file's | |
1043 buffer if the variable @code{auto-save-default} is non-@code{nil} (but not | |
1044 in batch mode; @pxref{Entering Emacs}). The default for this variable is | |
1045 @code{t}, so auto-saving is the usual practice for file-visiting buffers. | |
1046 Auto-saving can be turned on or off for any existing buffer with the | |
1047 command @kbd{M-x auto-save-mode}. Like other minor mode commands, @kbd{M-x | |
1048 auto-save-mode} turns auto-saving on with a positive argument, off with a | |
1049 zero or negative argument; with no argument, it toggles. | |
1050 | |
1051 @vindex auto-save-interval | |
1052 Emacs does auto-saving periodically based on counting how many characters | |
1053 you have typed since the last time auto-saving was done. The variable | |
1054 @code{auto-save-interval} specifies how many characters there are between | |
1055 auto-saves. By default, it is 300. Emacs doesn't accept values that are | |
1056 too small: if you customize @code{auto-save-interval} to a value less | |
1057 than 20, Emacs will behave as if the value is 20. | |
1058 | |
1059 @vindex auto-save-timeout | |
1060 Auto-saving also takes place when you stop typing for a while. The | |
1061 variable @code{auto-save-timeout} says how many seconds Emacs should | |
1062 wait before it does an auto save (and perhaps also a garbage | |
1063 collection). (The actual time period is longer if the current buffer is | |
1064 long; this is a heuristic which aims to keep out of your way when you | |
1065 are editing long buffers, in which auto-save takes an appreciable amount | |
1066 of time.) Auto-saving during idle periods accomplishes two things: | |
1067 first, it makes sure all your work is saved if you go away from the | |
1068 terminal for a while; second, it may avoid some auto-saving while you | |
1069 are actually typing. | |
1070 | |
1071 Emacs also does auto-saving whenever it gets a fatal error. This | |
1072 includes killing the Emacs job with a shell command such as @samp{kill | |
1073 %emacs}, or disconnecting a phone line or network connection. | |
1074 | |
1075 @findex do-auto-save | |
1076 You can request an auto-save explicitly with the command @kbd{M-x | |
1077 do-auto-save}. | |
1078 | |
1079 @node Recover | |
1080 @subsection Recovering Data from Auto-Saves | |
1081 | |
1082 @findex recover-file | |
1083 You can use the contents of an auto-save file to recover from a loss | |
1084 of data with the command @kbd{M-x recover-file @key{RET} @var{file} | |
1085 @key{RET}}. This visits @var{file} and then (after your confirmation) | |
1086 restores the contents from its auto-save file @file{#@var{file}#}. | |
1087 You can then save with @kbd{C-x C-s} to put the recovered text into | |
1088 @var{file} itself. For example, to recover file @file{foo.c} from its | |
1089 auto-save file @file{#foo.c#}, do:@refill | |
1090 | |
1091 @example | |
1092 M-x recover-file @key{RET} foo.c @key{RET} | |
1093 yes @key{RET} | |
1094 C-x C-s | |
1095 @end example | |
1096 | |
1097 Before asking for confirmation, @kbd{M-x recover-file} displays a | |
1098 directory listing describing the specified file and the auto-save file, | |
1099 so you can compare their sizes and dates. If the auto-save file | |
1100 is older, @kbd{M-x recover-file} does not offer to read it. | |
1101 | |
1102 @findex recover-session | |
1103 If Emacs or the computer crashes, you can recover all the files you | |
1104 were editing from their auto save files with the command @kbd{M-x | |
1105 recover-session}. This first shows you a list of recorded interrupted | |
1106 sessions. Move point to the one you choose, and type @kbd{C-c C-c}. | |
1107 | |
1108 Then @code{recover-session} asks about each of the files that were | |
1109 being edited during that session, asking whether to recover that file. | |
1110 If you answer @kbd{y}, it calls @code{recover-file}, which works in its | |
1111 normal fashion. It shows the dates of the original file and its | |
1112 auto-save file, and asks once again whether to recover that file. | |
1113 | |
1114 When @code{recover-session} is done, the files you've chosen to | |
1115 recover are present in Emacs buffers. You should then save them. Only | |
1116 this---saving them---updates the files themselves. | |
1117 | |
1118 @vindex auto-save-list-file-prefix | |
1119 Emacs records information about interrupted sessions for later | |
1120 recovery in files named | |
98636
d7df7c98fed8
(File Names): Reorganize description.
Chong Yidong <cyd@stupidchicken.com>
parents:
98263
diff
changeset
|
1121 @file{~/.emacs.d/auto-save-list/.saves-@var{pid}-@var{hostname}}. The |
d7df7c98fed8
(File Names): Reorganize description.
Chong Yidong <cyd@stupidchicken.com>
parents:
98263
diff
changeset
|
1122 directory used, @file{~/.emacs.d/auto-save-list/}, is determined by |
d7df7c98fed8
(File Names): Reorganize description.
Chong Yidong <cyd@stupidchicken.com>
parents:
98263
diff
changeset
|
1123 the variable @code{auto-save-list-file-prefix}. You can record |
84239 | 1124 sessions in a different place by customizing that variable. If you |
1125 set @code{auto-save-list-file-prefix} to @code{nil} in your | |
1126 @file{.emacs} file, sessions are not recorded for recovery. | |
1127 | |
1128 @node File Aliases | |
1129 @section File Name Aliases | |
1130 @cindex symbolic links (visiting) | |
1131 @cindex hard links (visiting) | |
1132 | |
1133 Symbolic links and hard links both make it possible for several file | |
1134 names to refer to the same file. Hard links are alternate names that | |
1135 refer directly to the file; all the names are equally valid, and no one | |
1136 of them is preferred. By contrast, a symbolic link is a kind of defined | |
1137 alias: when @file{foo} is a symbolic link to @file{bar}, you can use | |
1138 either name to refer to the file, but @file{bar} is the real name, while | |
1139 @file{foo} is just an alias. More complex cases occur when symbolic | |
1140 links point to directories. | |
1141 | |
1142 @vindex find-file-existing-other-name | |
1143 @vindex find-file-suppress-same-file-warnings | |
1144 | |
1145 Normally, if you visit a file which Emacs is already visiting under | |
1146 a different name, Emacs displays a message in the echo area and uses | |
1147 the existing buffer visiting that file. This can happen on systems | |
1148 that support hard or symbolic links, or if you use a long file name on | |
1149 a system that truncates long file names, or on a case-insensitive file | |
1150 system. You can suppress the message by setting the variable | |
1151 @code{find-file-suppress-same-file-warnings} to a non-@code{nil} | |
1152 value. You can disable this feature entirely by setting the variable | |
1153 @code{find-file-existing-other-name} to @code{nil}: then if you visit | |
1154 the same file under two different names, you get a separate buffer for | |
1155 each file name. | |
1156 | |
1157 @vindex find-file-visit-truename | |
1158 @cindex truenames of files | |
1159 @cindex file truenames | |
1160 If the variable @code{find-file-visit-truename} is non-@code{nil}, | |
1161 then the file name recorded for a buffer is the file's @dfn{truename} | |
1162 (made by replacing all symbolic links with their target names), rather | |
1163 than the name you specify. Setting @code{find-file-visit-truename} also | |
1164 implies the effect of @code{find-file-existing-other-name}. | |
1165 | |
1166 @node Version Control | |
1167 @section Version Control | |
1168 @cindex version control | |
1169 | |
98767
abb63d1375ec
(File Names): Reorganize description.
Chong Yidong <cyd@stupidchicken.com>
parents:
98636
diff
changeset
|
1170 A @dfn{version control system} is a package that can record multiple |
abb63d1375ec
(File Names): Reorganize description.
Chong Yidong <cyd@stupidchicken.com>
parents:
98636
diff
changeset
|
1171 versions of a source file, storing information such as the creation |
abb63d1375ec
(File Names): Reorganize description.
Chong Yidong <cyd@stupidchicken.com>
parents:
98636
diff
changeset
|
1172 time of each version, who created it, and a description of what was |
abb63d1375ec
(File Names): Reorganize description.
Chong Yidong <cyd@stupidchicken.com>
parents:
98636
diff
changeset
|
1173 changed in that version. |
84239 | 1174 |
1175 The Emacs version control interface is called VC. Its commands work | |
99002
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
1176 with several different version control systems; currently, it supports |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
1177 GNU Arch, Bazaar, CVS, Git, Mercurial, Monotone, RCS, SCCS/CSSC, and |
98767
abb63d1375ec
(File Names): Reorganize description.
Chong Yidong <cyd@stupidchicken.com>
parents:
98636
diff
changeset
|
1178 Subversion. Of these, the GNU project distributes CVS, GNU Arch, RCS, |
abb63d1375ec
(File Names): Reorganize description.
Chong Yidong <cyd@stupidchicken.com>
parents:
98636
diff
changeset
|
1179 and Bazaar. |
abb63d1375ec
(File Names): Reorganize description.
Chong Yidong <cyd@stupidchicken.com>
parents:
98636
diff
changeset
|
1180 |
abb63d1375ec
(File Names): Reorganize description.
Chong Yidong <cyd@stupidchicken.com>
parents:
98636
diff
changeset
|
1181 VC is enabled automatically whenever you visit a file that is |
abb63d1375ec
(File Names): Reorganize description.
Chong Yidong <cyd@stupidchicken.com>
parents:
98636
diff
changeset
|
1182 governed by a version control system. To disable VC entirely, set the |
84239 | 1183 customizable variable @code{vc-handled-backends} to @code{nil} |
1184 @iftex | |
1185 (@pxref{Customizing VC,,,emacs-xtra, Specialized Emacs Features}). | |
1186 @end iftex | |
1187 @ifnottex | |
1188 (@pxref{Customizing VC}). | |
1189 @end ifnottex | |
1190 | |
1191 | |
1192 @menu | |
1193 * Introduction to VC:: How version control works in general. | |
1194 * VC Mode Line:: How the mode line shows version control status. | |
1195 * Basic VC Editing:: How to edit a file under version control. | |
85139
8ba0e30716a5
Terminology cleanup.
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85135
diff
changeset
|
1196 * Old Revisions:: Examining and comparing old versions. |
84239 | 1197 * Secondary VC Commands:: The commands used a little less frequently. |
99002
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
1198 * VC Directory Mode:: Listing files managed by version control. |
84239 | 1199 * Branches:: Multiple lines of development. |
1200 @ifnottex | |
1201 * Remote Repositories:: Efficient access to remote CVS servers. | |
95020
4da572dc4992
Snapshot primitives globally renamed to refer to tags, documentation updated.
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
94838
diff
changeset
|
1202 * Revision Tags:: Symbolic names for revisions |
84239 | 1203 * Miscellaneous VC:: Various other commands and features of VC. |
1204 * Customizing VC:: Variables that change VC's behavior. | |
1205 @end ifnottex | |
1206 @end menu | |
1207 | |
1208 @node Introduction to VC | |
1209 @subsection Introduction to Version Control | |
1210 | |
1211 VC allows you to use a version control system from within Emacs, | |
85061
46ed9943a6fd
Update manual for 2007 conditions. None of these changes are
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
84239
diff
changeset
|
1212 integrating the version control operations smoothly with editing. |
99002
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
1213 Though VC cannot completely bridge the gaps between version control |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
1214 systems with widely differing capabilities, it does provide a uniform |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
1215 interface to many version control operations. Regardless of which |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
1216 version control system is in use, you will be able to do basic |
85061
46ed9943a6fd
Update manual for 2007 conditions. None of these changes are
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
84239
diff
changeset
|
1217 operations in much the same way. |
84239 | 1218 |
1219 This section provides a general overview of version control, and | |
1220 describes the version control systems that VC supports. You can skip | |
1221 this section if you are already familiar with the version control system | |
1222 you want to use. | |
1223 | |
1224 @menu | |
85135
07ce6e2515dd
Fix sectrioning errors in files.texi.
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85133
diff
changeset
|
1225 * Why Version Control?:: Understanding the problems it addresses |
07ce6e2515dd
Fix sectrioning errors in files.texi.
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85133
diff
changeset
|
1226 * Version Control Systems:: Supported version control back-end systems. |
07ce6e2515dd
Fix sectrioning errors in files.texi.
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85133
diff
changeset
|
1227 * VCS Concepts:: Words and concepts related to version control. |
07ce6e2515dd
Fix sectrioning errors in files.texi.
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85133
diff
changeset
|
1228 * Types of Log File:: The VCS log in contrast to the ChangeLog. |
84239 | 1229 @end menu |
1230 | |
1231 @node Why Version Control? | |
1232 @subsubsection Understanding the problems it addresses | |
1233 | |
99002
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
1234 Version control systems provide you with three important |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
1235 capabilities: |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
1236 |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
1237 @itemize @bullet |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
1238 @item |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
1239 @dfn{Reversibility}: the ability to back up to a previous state if you |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
1240 discover that some modification you did was a mistake or a bad idea. |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
1241 |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
1242 @item |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
1243 @dfn{Concurrency}: the ability to have many people modifying the same |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
1244 collection of files knowing that conflicting modifications can be |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
1245 detected and resolved. |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
1246 |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
1247 @item |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
1248 @dfn{History}: the ability to attach historical data to your data, |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
1249 such as explanatory comments about the intention behind each change to |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
1250 it. Even for a programmer working solo, change histories are an |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
1251 important aid to memory; for a multi-person project, they are a |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
1252 vitally important form of communication among developers. |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
1253 @end itemize |
84239 | 1254 |
85135
07ce6e2515dd
Fix sectrioning errors in files.texi.
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85133
diff
changeset
|
1255 @node Version Control Systems |
84239 | 1256 @subsubsection Supported Version Control Systems |
1257 | |
1258 @cindex back end (version control) | |
94730
3bbff46b7130
Meta-CVS support removed.
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
94541
diff
changeset
|
1259 VC currently works with many different version control systems or |
98775
91b65d9aa48b
(Version Control Systems): Fix last change.
Eli Zaretskii <eliz@gnu.org>
parents:
98767
diff
changeset
|
1260 @dfn{back ends}: |
98767
abb63d1375ec
(File Names): Reorganize description.
Chong Yidong <cyd@stupidchicken.com>
parents:
98636
diff
changeset
|
1261 |
abb63d1375ec
(File Names): Reorganize description.
Chong Yidong <cyd@stupidchicken.com>
parents:
98636
diff
changeset
|
1262 @itemize @bullet |
abb63d1375ec
(File Names): Reorganize description.
Chong Yidong <cyd@stupidchicken.com>
parents:
98636
diff
changeset
|
1263 |
85123
4f909d0fbec8
Added descriptions of newer supported version control systems. Arranged all in
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85063
diff
changeset
|
1264 @cindex SCCS |
98767
abb63d1375ec
(File Names): Reorganize description.
Chong Yidong <cyd@stupidchicken.com>
parents:
98636
diff
changeset
|
1265 @item |
abb63d1375ec
(File Names): Reorganize description.
Chong Yidong <cyd@stupidchicken.com>
parents:
98636
diff
changeset
|
1266 SCCS was the first version control system ever built, and was long ago |
99002
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
1267 superseded by more advanced ones. VC compensates for certain features |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
1268 missing in SCCS (e.g., tag names for releases) by implementing them |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
1269 itself. Other VC features, such as multiple branches, are simply |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
1270 unavailable. Since SCCS is non-free, we recommend avoiding it. |
98767
abb63d1375ec
(File Names): Reorganize description.
Chong Yidong <cyd@stupidchicken.com>
parents:
98636
diff
changeset
|
1271 |
abb63d1375ec
(File Names): Reorganize description.
Chong Yidong <cyd@stupidchicken.com>
parents:
98636
diff
changeset
|
1272 @cindex CSSC |
abb63d1375ec
(File Names): Reorganize description.
Chong Yidong <cyd@stupidchicken.com>
parents:
98636
diff
changeset
|
1273 @item |
abb63d1375ec
(File Names): Reorganize description.
Chong Yidong <cyd@stupidchicken.com>
parents:
98636
diff
changeset
|
1274 CSSC is a free replacement for SCCS. You should use CSSC only if, for |
99002
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
1275 some reason, you cannot use a more recent and better-designed version |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
1276 control system. |
85123
4f909d0fbec8
Added descriptions of newer supported version control systems. Arranged all in
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85063
diff
changeset
|
1277 |
4f909d0fbec8
Added descriptions of newer supported version control systems. Arranged all in
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85063
diff
changeset
|
1278 @cindex RCS |
98767
abb63d1375ec
(File Names): Reorganize description.
Chong Yidong <cyd@stupidchicken.com>
parents:
98636
diff
changeset
|
1279 @item |
abb63d1375ec
(File Names): Reorganize description.
Chong Yidong <cyd@stupidchicken.com>
parents:
98636
diff
changeset
|
1280 RCS is the free version control system around which VC was initially |
abb63d1375ec
(File Names): Reorganize description.
Chong Yidong <cyd@stupidchicken.com>
parents:
98636
diff
changeset
|
1281 built. Almost everything you can do with RCS can be done through VC. |
abb63d1375ec
(File Names): Reorganize description.
Chong Yidong <cyd@stupidchicken.com>
parents:
98636
diff
changeset
|
1282 However, you cannot use RCS over the network, and it only works at the |
abb63d1375ec
(File Names): Reorganize description.
Chong Yidong <cyd@stupidchicken.com>
parents:
98636
diff
changeset
|
1283 level of individual files rather than projects. |
84239 | 1284 |
1285 @cindex CVS | |
98767
abb63d1375ec
(File Names): Reorganize description.
Chong Yidong <cyd@stupidchicken.com>
parents:
98636
diff
changeset
|
1286 @item |
abb63d1375ec
(File Names): Reorganize description.
Chong Yidong <cyd@stupidchicken.com>
parents:
98636
diff
changeset
|
1287 CVS is the free version control system that was, until recently (circa |
99002
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
1288 2008), used by the majority of free software projects. Nowadays, it |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
1289 is slowly being superseded by newer systems. CVS allows concurrent |
98767
abb63d1375ec
(File Names): Reorganize description.
Chong Yidong <cyd@stupidchicken.com>
parents:
98636
diff
changeset
|
1290 multi-user development either locally or over the network. It lacks |
abb63d1375ec
(File Names): Reorganize description.
Chong Yidong <cyd@stupidchicken.com>
parents:
98636
diff
changeset
|
1291 support for atomic commits or file moving/renaming. VC supports all |
abb63d1375ec
(File Names): Reorganize description.
Chong Yidong <cyd@stupidchicken.com>
parents:
98636
diff
changeset
|
1292 basic editing operations under CVS. For some less common tasks, you |
abb63d1375ec
(File Names): Reorganize description.
Chong Yidong <cyd@stupidchicken.com>
parents:
98636
diff
changeset
|
1293 still need to call CVS from the command line. Note also that before |
abb63d1375ec
(File Names): Reorganize description.
Chong Yidong <cyd@stupidchicken.com>
parents:
98636
diff
changeset
|
1294 using CVS you must set up a repository, which is a subject too complex |
abb63d1375ec
(File Names): Reorganize description.
Chong Yidong <cyd@stupidchicken.com>
parents:
98636
diff
changeset
|
1295 to treat here. |
84239 | 1296 |
85123
4f909d0fbec8
Added descriptions of newer supported version control systems. Arranged all in
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85063
diff
changeset
|
1297 @cindex SVN |
4f909d0fbec8
Added descriptions of newer supported version control systems. Arranged all in
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85063
diff
changeset
|
1298 @cindex Subversion |
98767
abb63d1375ec
(File Names): Reorganize description.
Chong Yidong <cyd@stupidchicken.com>
parents:
98636
diff
changeset
|
1299 @item |
abb63d1375ec
(File Names): Reorganize description.
Chong Yidong <cyd@stupidchicken.com>
parents:
98636
diff
changeset
|
1300 Subversion (SVN) is a free version control system designed to be |
abb63d1375ec
(File Names): Reorganize description.
Chong Yidong <cyd@stupidchicken.com>
parents:
98636
diff
changeset
|
1301 similar to CVS but without its problems. It supports atomic commits |
abb63d1375ec
(File Names): Reorganize description.
Chong Yidong <cyd@stupidchicken.com>
parents:
98636
diff
changeset
|
1302 of filesets, and versioning of directories, symbolic links, meta-data, |
abb63d1375ec
(File Names): Reorganize description.
Chong Yidong <cyd@stupidchicken.com>
parents:
98636
diff
changeset
|
1303 renames, copies, and deletes. |
85123
4f909d0fbec8
Added descriptions of newer supported version control systems. Arranged all in
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85063
diff
changeset
|
1304 |
84239 | 1305 @cindex GNU Arch |
1306 @cindex Arch | |
98767
abb63d1375ec
(File Names): Reorganize description.
Chong Yidong <cyd@stupidchicken.com>
parents:
98636
diff
changeset
|
1307 @item |
abb63d1375ec
(File Names): Reorganize description.
Chong Yidong <cyd@stupidchicken.com>
parents:
98636
diff
changeset
|
1308 GNU Arch is a version control system designed for distributed work. |
abb63d1375ec
(File Names): Reorganize description.
Chong Yidong <cyd@stupidchicken.com>
parents:
98636
diff
changeset
|
1309 It differs in many ways from older systems like CVS and RCS. It |
abb63d1375ec
(File Names): Reorganize description.
Chong Yidong <cyd@stupidchicken.com>
parents:
98636
diff
changeset
|
1310 provides different methods for interoperating between users, support |
abb63d1375ec
(File Names): Reorganize description.
Chong Yidong <cyd@stupidchicken.com>
parents:
98636
diff
changeset
|
1311 for offline operations, and good branching and merging features. It |
abb63d1375ec
(File Names): Reorganize description.
Chong Yidong <cyd@stupidchicken.com>
parents:
98636
diff
changeset
|
1312 also supports atomic commits of filesets and file moving/renaming. VC |
85123
4f909d0fbec8
Added descriptions of newer supported version control systems. Arranged all in
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85063
diff
changeset
|
1313 does not support all operations provided by GNU Arch, so you must |
98767
abb63d1375ec
(File Names): Reorganize description.
Chong Yidong <cyd@stupidchicken.com>
parents:
98636
diff
changeset
|
1314 sometimes invoke it from the command line. |
85123
4f909d0fbec8
Added descriptions of newer supported version control systems. Arranged all in
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85063
diff
changeset
|
1315 |
4f909d0fbec8
Added descriptions of newer supported version control systems. Arranged all in
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85063
diff
changeset
|
1316 @cindex git |
98767
abb63d1375ec
(File Names): Reorganize description.
Chong Yidong <cyd@stupidchicken.com>
parents:
98636
diff
changeset
|
1317 @item |
98775
91b65d9aa48b
(Version Control Systems): Fix last change.
Eli Zaretskii <eliz@gnu.org>
parents:
98767
diff
changeset
|
1318 Git is a distributed version control system invented by Linus Torvalds to support |
98767
abb63d1375ec
(File Names): Reorganize description.
Chong Yidong <cyd@stupidchicken.com>
parents:
98636
diff
changeset
|
1319 Linux kernel development. It supports atomic commits of filesets and |
abb63d1375ec
(File Names): Reorganize description.
Chong Yidong <cyd@stupidchicken.com>
parents:
98636
diff
changeset
|
1320 file moving/renaming. One significant feature of git is that it |
abb63d1375ec
(File Names): Reorganize description.
Chong Yidong <cyd@stupidchicken.com>
parents:
98636
diff
changeset
|
1321 largely abolishes the notion of a single centralized repository; |
abb63d1375ec
(File Names): Reorganize description.
Chong Yidong <cyd@stupidchicken.com>
parents:
98636
diff
changeset
|
1322 instead, each working copy of a git project is its own repository and |
abb63d1375ec
(File Names): Reorganize description.
Chong Yidong <cyd@stupidchicken.com>
parents:
98636
diff
changeset
|
1323 coordination is done through repository-sync operations. VC supports |
abb63d1375ec
(File Names): Reorganize description.
Chong Yidong <cyd@stupidchicken.com>
parents:
98636
diff
changeset
|
1324 most git operations, with the exception of news merges and repository |
abb63d1375ec
(File Names): Reorganize description.
Chong Yidong <cyd@stupidchicken.com>
parents:
98636
diff
changeset
|
1325 syncing; these must be done from the command line. |
85123
4f909d0fbec8
Added descriptions of newer supported version control systems. Arranged all in
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85063
diff
changeset
|
1326 |
4f909d0fbec8
Added descriptions of newer supported version control systems. Arranged all in
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85063
diff
changeset
|
1327 @cindex hg |
4f909d0fbec8
Added descriptions of newer supported version control systems. Arranged all in
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85063
diff
changeset
|
1328 @cindex Mercurial |
98767
abb63d1375ec
(File Names): Reorganize description.
Chong Yidong <cyd@stupidchicken.com>
parents:
98636
diff
changeset
|
1329 @item |
abb63d1375ec
(File Names): Reorganize description.
Chong Yidong <cyd@stupidchicken.com>
parents:
98636
diff
changeset
|
1330 Mercurial (hg) is a distributed version control system broadly |
abb63d1375ec
(File Names): Reorganize description.
Chong Yidong <cyd@stupidchicken.com>
parents:
98636
diff
changeset
|
1331 resembling GNU Arch and git, with atomic fileset commits and file |
abb63d1375ec
(File Names): Reorganize description.
Chong Yidong <cyd@stupidchicken.com>
parents:
98636
diff
changeset
|
1332 moving/renaming. Like git, it is fully decentralized. VC supports |
abb63d1375ec
(File Names): Reorganize description.
Chong Yidong <cyd@stupidchicken.com>
parents:
98636
diff
changeset
|
1333 most Mercurial commands, with the exception of repository sync |
abb63d1375ec
(File Names): Reorganize description.
Chong Yidong <cyd@stupidchicken.com>
parents:
98636
diff
changeset
|
1334 operations; this needs to be done from the command line. |
abb63d1375ec
(File Names): Reorganize description.
Chong Yidong <cyd@stupidchicken.com>
parents:
98636
diff
changeset
|
1335 |
abb63d1375ec
(File Names): Reorganize description.
Chong Yidong <cyd@stupidchicken.com>
parents:
98636
diff
changeset
|
1336 @cindex bzr |
abb63d1375ec
(File Names): Reorganize description.
Chong Yidong <cyd@stupidchicken.com>
parents:
98636
diff
changeset
|
1337 @cindex Bazaar |
abb63d1375ec
(File Names): Reorganize description.
Chong Yidong <cyd@stupidchicken.com>
parents:
98636
diff
changeset
|
1338 @item |
98775
91b65d9aa48b
(Version Control Systems): Fix last change.
Eli Zaretskii <eliz@gnu.org>
parents:
98767
diff
changeset
|
1339 Bazaar (bzr) is a distributed version control system that supports both |
98767
abb63d1375ec
(File Names): Reorganize description.
Chong Yidong <cyd@stupidchicken.com>
parents:
98636
diff
changeset
|
1340 repository-based and distributed versioning, with atomic fileset |
abb63d1375ec
(File Names): Reorganize description.
Chong Yidong <cyd@stupidchicken.com>
parents:
98636
diff
changeset
|
1341 commits and file moving/renaming. VC supports most basic editing |
abb63d1375ec
(File Names): Reorganize description.
Chong Yidong <cyd@stupidchicken.com>
parents:
98636
diff
changeset
|
1342 operations under Bazaar. |
abb63d1375ec
(File Names): Reorganize description.
Chong Yidong <cyd@stupidchicken.com>
parents:
98636
diff
changeset
|
1343 @end itemize |
84239 | 1344 |
99002
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
1345 Previous versions of VC supported a version control system known as |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
1346 Meta-CVS. This support has been dropped because of limited interest |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
1347 from users and developers. |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
1348 |
85135
07ce6e2515dd
Fix sectrioning errors in files.texi.
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85133
diff
changeset
|
1349 @node VCS Concepts |
84239 | 1350 @subsubsection Concepts of Version Control |
1351 | |
85061
46ed9943a6fd
Update manual for 2007 conditions. None of these changes are
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
84239
diff
changeset
|
1352 @cindex repository |
84239 | 1353 @cindex registered file |
98767
abb63d1375ec
(File Names): Reorganize description.
Chong Yidong <cyd@stupidchicken.com>
parents:
98636
diff
changeset
|
1354 When a file is under version control, we say that it is |
85061
46ed9943a6fd
Update manual for 2007 conditions. None of these changes are
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
84239
diff
changeset
|
1355 @dfn{registered} in the version control system. The system has a |
98767
abb63d1375ec
(File Names): Reorganize description.
Chong Yidong <cyd@stupidchicken.com>
parents:
98636
diff
changeset
|
1356 @dfn{repository} which stores both the file's present state and its |
85061
46ed9943a6fd
Update manual for 2007 conditions. None of these changes are
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
84239
diff
changeset
|
1357 change history---enough to reconstruct the current version or any |
98767
abb63d1375ec
(File Names): Reorganize description.
Chong Yidong <cyd@stupidchicken.com>
parents:
98636
diff
changeset
|
1358 earlier version. The repository also contains other information, such |
abb63d1375ec
(File Names): Reorganize description.
Chong Yidong <cyd@stupidchicken.com>
parents:
98636
diff
changeset
|
1359 as @dfn{log entries} that describe the changes made to each file. |
84239 | 1360 |
1361 @cindex work file | |
1362 @cindex checking out files | |
98767
abb63d1375ec
(File Names): Reorganize description.
Chong Yidong <cyd@stupidchicken.com>
parents:
98636
diff
changeset
|
1363 A file @dfn{checked out} of a repository is called the @dfn{work |
abb63d1375ec
(File Names): Reorganize description.
Chong Yidong <cyd@stupidchicken.com>
parents:
98636
diff
changeset
|
1364 file}. You edit the work file and make changes in it, as you would |
abb63d1375ec
(File Names): Reorganize description.
Chong Yidong <cyd@stupidchicken.com>
parents:
98636
diff
changeset
|
1365 with an ordinary file. After you are done with a set of changes, you |
abb63d1375ec
(File Names): Reorganize description.
Chong Yidong <cyd@stupidchicken.com>
parents:
98636
diff
changeset
|
1366 @dfn{check in} or @dfn{commit} the file; this records the changes in |
abb63d1375ec
(File Names): Reorganize description.
Chong Yidong <cyd@stupidchicken.com>
parents:
98636
diff
changeset
|
1367 the repository, along with a log entry for those changes. |
85152
a0d3d8180a58
Revise version-control portions of the manual to include
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85139
diff
changeset
|
1368 |
a0d3d8180a58
Revise version-control portions of the manual to include
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85139
diff
changeset
|
1369 @cindex revision |
a0d3d8180a58
Revise version-control portions of the manual to include
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85139
diff
changeset
|
1370 @cindex revision ID |
a0d3d8180a58
Revise version-control portions of the manual to include
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85139
diff
changeset
|
1371 A copy of a file stored in a repository is called a @dfn{revision}. |
a0d3d8180a58
Revise version-control portions of the manual to include
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85139
diff
changeset
|
1372 The history of a file is a sequence of revisions. Each revisions is |
98767
abb63d1375ec
(File Names): Reorganize description.
Chong Yidong <cyd@stupidchicken.com>
parents:
98636
diff
changeset
|
1373 named by a @dfn{revision ID}. The format of the revision ID depends |
abb63d1375ec
(File Names): Reorganize description.
Chong Yidong <cyd@stupidchicken.com>
parents:
98636
diff
changeset
|
1374 on the version control system; in the simplest case, it is just an |
abb63d1375ec
(File Names): Reorganize description.
Chong Yidong <cyd@stupidchicken.com>
parents:
98636
diff
changeset
|
1375 integer. |
84239 | 1376 |
1377 To go beyond these basic concepts, you will need to understand three | |
99002
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
1378 ways in which version control systems can differ from each other. |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
1379 They can be locking-based or merging-based; they can be file-based or |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
1380 changeset-based; and they can be centralized or decentralized. VC |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
1381 handles all these choices, but they lead to differing behaviors which |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
1382 you will need to understand as you use it. |
84239 | 1383 |
1384 @cindex locking versus merging | |
1385 A version control system typically has some mechanism to coordinate | |
98767
abb63d1375ec
(File Names): Reorganize description.
Chong Yidong <cyd@stupidchicken.com>
parents:
98636
diff
changeset
|
1386 between users who want to change the same file. There are two ways to |
99002
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
1387 do this: merging and locking. |
98767
abb63d1375ec
(File Names): Reorganize description.
Chong Yidong <cyd@stupidchicken.com>
parents:
98636
diff
changeset
|
1388 |
abb63d1375ec
(File Names): Reorganize description.
Chong Yidong <cyd@stupidchicken.com>
parents:
98636
diff
changeset
|
1389 In a version control system that uses merging, each user may check |
99002
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
1390 out and modify a work file at any time. The system lets you |
98767
abb63d1375ec
(File Names): Reorganize description.
Chong Yidong <cyd@stupidchicken.com>
parents:
98636
diff
changeset
|
1391 @dfn{merge} your work file, which may contain changes that have not |
abb63d1375ec
(File Names): Reorganize description.
Chong Yidong <cyd@stupidchicken.com>
parents:
98636
diff
changeset
|
1392 been checked in, with the latest changes that others have checked into |
abb63d1375ec
(File Names): Reorganize description.
Chong Yidong <cyd@stupidchicken.com>
parents:
98636
diff
changeset
|
1393 the repository. |
84239 | 1394 |
99002
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
1395 Older version control systems use a @dfn{locking} scheme instead. |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
1396 Here, work files are normally read-only. To edit a file, you ask the |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
1397 version control system to make it writable for you by @dfn{locking} |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
1398 it; only one user can lock a given file at any given time. This |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
1399 procedure is analogous to, but different from, the locking that Emacs |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
1400 uses to detect simultaneous editing of ordinary files |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
1401 (@pxref{Interlocking}). When you check in your changes, that unlocks |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
1402 the file, and the work file becomes read-only again. Other users may |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
1403 then lock the file to make their own changes. |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
1404 |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
1405 Both locking and merging systems can have problems when multiple |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
1406 users try to modify the same file at the same time. Locking systems |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
1407 have @dfn{lock conflicts}; a user may try to check a file out and be |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
1408 unable to because it is locked. In merging systems, @dfn{merge |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
1409 conflicts} happen when you check in a change to a file that conflicts |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
1410 with a change checked in by someone else after your checkout. Both |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
1411 kinds of conflict have to be resolved by human judgment and |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
1412 communication. |
84239 | 1413 |
86364
7842eb213688
(Why Version Control): Fix typo.
Thien-Thi Nguyen <ttn@gnuvola.org>
parents:
85473
diff
changeset
|
1414 SCCS always uses locking. RCS is lock-based by default but can be |
85152
a0d3d8180a58
Revise version-control portions of the manual to include
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85139
diff
changeset
|
1415 told to operate in a merging style. CVS and Subversion are |
a0d3d8180a58
Revise version-control portions of the manual to include
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85139
diff
changeset
|
1416 merge-based by default but can be told to operate in a locking mode. |
99002
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
1417 Distributed version control systems, such as GNU Arch, git, and |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
1418 Mercurial, are exclusively merging-based. Experience has shown that |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
1419 merging is superior to locking, both in convenience to developers and |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
1420 in minimizing the number and severity of conflicts that actually |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
1421 occur. Sometimes, however, newer version control systems may have |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
1422 locks retrofitted onto them for reasons having nothing to do with |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
1423 technology@footnote{Usually the control-freak instincts of managers.}. |
98767
abb63d1375ec
(File Names): Reorganize description.
Chong Yidong <cyd@stupidchicken.com>
parents:
98636
diff
changeset
|
1424 |
abb63d1375ec
(File Names): Reorganize description.
Chong Yidong <cyd@stupidchicken.com>
parents:
98636
diff
changeset
|
1425 VC mode supports both locking and merging version control and tries |
abb63d1375ec
(File Names): Reorganize description.
Chong Yidong <cyd@stupidchicken.com>
parents:
98636
diff
changeset
|
1426 to hide the differences between them as much as possible. |
84239 | 1427 |
1428 @cindex files versus changesets. | |
99002
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
1429 On SCCS, RCS, CVS, and other early version control systems, version |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
1430 control operations are @dfn{file-based}: each file has its own comment |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
1431 and revision history separate from that of all other files in the |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
1432 system. Later systems, beginning with Subversion, are |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
1433 @dfn{changeset-based}: a checkin may include changes to several files, |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
1434 and the entire set of changes is treated as a unit by the system. Any |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
1435 comment associated with the change does not belong to a single file, |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
1436 but to the changeset itself. |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
1437 |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
1438 Changeset-based version control is more flexible and powerful than |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
1439 file-based version control; usually, when a change to multiple files |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
1440 has to be reversed, it's good to be able to easily identify and remove |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
1441 all of it. But it took some years for designers to figure that out, |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
1442 and while file-based systems are passing out of use, there are lots of |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
1443 legacy repositories still to be dealt with as of this writing (2008). |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
1444 |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
1445 Prior to Emacs 23, VC supported only file-based systems, leading to |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
1446 unhappy results when it was used to drive changeset-based |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
1447 systems---the Subversion support, for example, used to break up |
98767
abb63d1375ec
(File Names): Reorganize description.
Chong Yidong <cyd@stupidchicken.com>
parents:
98636
diff
changeset
|
1448 changesets into multiple per-file commits. This has been fixed, but |
99002
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
1449 it has left a mark in VC's terminology. The terms ``checkin'' and |
98767
abb63d1375ec
(File Names): Reorganize description.
Chong Yidong <cyd@stupidchicken.com>
parents:
98636
diff
changeset
|
1450 ``checkout'' are associated with file-based and locking-based systems |
abb63d1375ec
(File Names): Reorganize description.
Chong Yidong <cyd@stupidchicken.com>
parents:
98636
diff
changeset
|
1451 and a bit archaic; nowadays those operations are usually called |
85133
87df82f093bd
New VC command docs for the Emacs manual.
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85123
diff
changeset
|
1452 ``commit'' and ``update''. |
87df82f093bd
New VC command docs for the Emacs manual.
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85123
diff
changeset
|
1453 |
99002
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
1454 @cindex centralized vs. decentralized version control |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
1455 Early version control systems were designed around a |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
1456 @dfn{centralized} model in which each project has only one repository |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
1457 used by all developers. SCCS, RCS, CVS, and Subversion share this |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
1458 kind of model. One problem with this approach is that a single |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
1459 repository is a single point of failure---if the repository server is |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
1460 down, all work stops. |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
1461 |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
1462 Newer version control systems like GNU Arch, git, Mercurial, and |
98767
abb63d1375ec
(File Names): Reorganize description.
Chong Yidong <cyd@stupidchicken.com>
parents:
98636
diff
changeset
|
1463 Bazaar are @dfn{decentralized}. A project may have several different |
85152
a0d3d8180a58
Revise version-control portions of the manual to include
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85139
diff
changeset
|
1464 repositories, and these systems support a sort of super-merge between |
a0d3d8180a58
Revise version-control portions of the manual to include
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85139
diff
changeset
|
1465 repositories that tries to reconcile their change histories. At the |
a0d3d8180a58
Revise version-control portions of the manual to include
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85139
diff
changeset
|
1466 limit, each developer has his/her own repository, and repository |
a0d3d8180a58
Revise version-control portions of the manual to include
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85139
diff
changeset
|
1467 merges replace checkin/commit operations. |
84239 | 1468 |
1469 VC's job is to help you manage the traffic between your personal | |
99002
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
1470 workfiles and a repository. Whether that repository is a single |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
1471 master or one of a network of peer repositories is not something VC |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
1472 has to care about. Thus, the difference between a centralized and a |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
1473 decentralized version control system is invisible to VC mode. |
84239 | 1474 |
1475 @node Types of Log File | |
1476 @subsubsection Types of Log File | |
1477 @cindex types of log file | |
1478 @cindex log File, types of | |
1479 @cindex version control log | |
1480 | |
99002
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
1481 Projects that use a version control system can have two types of log |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
1482 for changes. One is the log maintained by the version control system: |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
1483 each time you check in a change, you fill out a @dfn{log entry} for |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
1484 the change (@pxref{Log Buffer}). This is called the @dfn{version |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
1485 control log}. |
84239 | 1486 |
1487 The other kind of log is the file @file{ChangeLog} (@pxref{Change | |
1488 Log}). It provides a chronological record of all changes to a large | |
1489 portion of a program---typically one directory and its subdirectories. | |
1490 A small program would use one @file{ChangeLog} file; a large program | |
99002
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
1491 may have a @file{ChangeLog} file in each major directory. |
84239 | 1492 @xref{Change Log}. |
1493 | |
99002
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
1494 Actually, the fact that both kinds of log exist is partly a legacy |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
1495 from file-based version control. Changelogs are a GNU convention, |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
1496 later more widely adopted, that help developers to get a |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
1497 changeset-based view of a project even when its version control system |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
1498 has that information split up in multiple file-based logs. |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
1499 |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
1500 Changeset-based version systems, on the other hand, often maintain a |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
1501 changeset-based modification log for the entire system that makes |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
1502 ChangeLogs somewhat redundant. One advantage that ChangeLogs retain |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
1503 is that it is sometimes useful to be able to view the transaction |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
1504 history of a single directory separately from those of other |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
1505 directories. |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
1506 |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
1507 A project maintained with version control can use just the version |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
1508 control log, or it can use both kinds of logs. It can handle some |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
1509 files one way and some files the other way. Each project has its |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
1510 policy, which you should follow. |
84239 | 1511 |
1512 When the policy is to use both, you typically want to write an entry | |
1513 for each change just once, then put it into both logs. You can write | |
99002
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
1514 the entry in @file{ChangeLog}, then copy it to the log buffer with |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
1515 @kbd{C-c C-a} when checking in the change (@pxref{Log Buffer}). Or |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
1516 you can write the entry in the log buffer while checking in the |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
1517 change, and later use the @kbd{C-x v a} command to copy it to |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
1518 @file{ChangeLog} |
84239 | 1519 @iftex |
1520 (@pxref{Change Logs and VC,,,emacs-xtra, Specialized Emacs Features}). | |
1521 @end iftex | |
1522 @ifnottex | |
1523 (@pxref{Change Logs and VC}). | |
1524 @end ifnottex | |
1525 | |
1526 @node VC Mode Line | |
1527 @subsection Version Control and the Mode Line | |
1528 | |
1529 When you visit a file that is under version control, Emacs indicates | |
1530 this on the mode line. For example, @samp{RCS-1.3} says that RCS is | |
1531 used for that file, and the current version is 1.3. | |
1532 | |
85152
a0d3d8180a58
Revise version-control portions of the manual to include
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85139
diff
changeset
|
1533 The character between the back-end name and the revision ID |
84239 | 1534 indicates the version control status of the file. @samp{-} means that |
1535 the work file is not locked (if locking is in use), or not modified (if | |
1536 locking is not in use). @samp{:} indicates that the file is locked, or | |
1537 that it is modified. If the file is locked by some other user (for | |
1538 instance, @samp{jim}), that is displayed as @samp{RCS:jim:1.3}. | |
1539 | |
99002
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
1540 On a graphical display, you can move the mouse over this mode line |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
1541 indicator to pop up a ``tool-tip'', which displays a more verbose |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
1542 description of the version control status. Pressing @key{Mouse-1} |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
1543 over the indicator pops up a menu of VC commands. This menu is |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
1544 identical to the @samp{Version Control} menu item, which can be found |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
1545 in the @samp{Tools} menu on the menu bar. |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
1546 |
84239 | 1547 @vindex auto-revert-check-vc-info |
1548 When Auto Revert mode (@pxref{Reverting}) reverts a buffer that is | |
1549 under version control, it updates the version control information in | |
1550 the mode line. However, Auto Revert mode may not properly update this | |
1551 information if the version control status changes without changes to | |
1552 the work file, from outside the current Emacs session. If you set | |
1553 @code{auto-revert-check-vc-info} to @code{t}, Auto Revert mode updates | |
1554 the version control status information every | |
1555 @code{auto-revert-interval} seconds, even if the work file itself is | |
1556 unchanged. The resulting CPU usage depends on the version control | |
1557 system, but is usually not excessive. | |
1558 | |
1559 @node Basic VC Editing | |
1560 @subsection Basic Editing under Version Control | |
1561 | |
85133
87df82f093bd
New VC command docs for the Emacs manual.
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85123
diff
changeset
|
1562 @cindex filesets |
99002
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
1563 Most VC commands operate on @dfn{VC filesets}. A VC fileset is a |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
1564 group of one or more files that are treated as a unit, for the |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
1565 purposes of version control. |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
1566 |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
1567 If you are visiting a version-controlled file in the current |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
1568 buffer, the VC fileset is simply that one file. If you are visiting a |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
1569 VC directory buffer, and some files in it are marked, the VC fileset |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
1570 consists of the marked files (@pxref{VC Directory Mode}). |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
1571 |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
1572 The principal VC command is an all-purpose command, @kbd{C-x v v} |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
1573 (@code{vc-next-action}), that performs either locking, merging or a |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
1574 check-in on the current VC fileset, depending on the situation. You |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
1575 can call @kbd{C-x v v} from a version-controlled file, or from the VC |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
1576 Directory buffer. |
84239 | 1577 |
1578 @table @kbd | |
1579 @itemx C-x v v | |
99002
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
1580 Perform the next logical version control operation on the VC fileset. |
84239 | 1581 @end table |
1582 | |
1583 @findex vc-next-action | |
1584 @kindex C-x v v | |
99002
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
1585 The precise action of @kbd{C-x v v} depends on the state of the VC |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
1586 fileset, and whether the version control system uses locking or |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
1587 merging. This is described in detail in the subsequent sections. |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
1588 |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
1589 VC filesets are the way that VC mode bridges the gap between |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
1590 file-based and changeset-based version control systems. They are, |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
1591 essentially, a way to pass multiple file arguments as a group to |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
1592 version control commands. For example, on Subversion, a checkin with |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
1593 a multi-file VC fileset becomes a joint commit, as though you had |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
1594 typed @command{svn commit} with those file arguments at the shell |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
1595 command line. All files in a VC fileset must be under the same |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
1596 version control system; if they are not, Emacs signals an error when |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
1597 you attempt to execute a command on the fileset. |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
1598 |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
1599 If you are accustomed to previous versions of VC, most of the |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
1600 changes to VC in Emacs 23 are found in VC directory mode (@pxref{VC |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
1601 Directory Mode}). When multiple files are marked in the VC directory |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
1602 buffer, they are treated as a VC fileset; typing @kbd{C-x v v} in the |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
1603 VC directory buffer passes them to the version control backends as a |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
1604 single unit. Other commands in VC directory mode now act on the VC |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
1605 fileset, rather than the file on the current line. These changes |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
1606 allow VC to interoperate correctly with changeset-based version |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
1607 control systems. |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
1608 |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
1609 VC filesets are distinct from the ``named filesets'' used for |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
1610 viewing and visiting files in functional groups (@pxref{Filesets}). |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
1611 Unlike named filesets, VC filesets are not named and don't persist |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
1612 across sessions. |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
1613 |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
1614 @menu |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
1615 * VC With A Merging VCS:: Without locking: default mode for CVS. |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
1616 * VC With A Locking VCS:: RCS in its default mode, SCCS, and optionally CVS. |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
1617 * Advanced C-x v v:: Advanced features available with a prefix argument. |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
1618 * Log Buffer:: Features available in log entry buffers. |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
1619 @end menu |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
1620 |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
1621 @node VC With A Merging VCS |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
1622 @subsubsection Basic Version Control with Merging |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
1623 |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
1624 When your version control system is merging-based (the default for |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
1625 CVS and all newer version control systems), work files are always |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
1626 writable; you need not do anything special to begin editing a file. |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
1627 The status indicator on the mode line is @samp{-} if the file is |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
1628 unmodified; it flips to @samp{:} as soon as you save any changes |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
1629 (@pxref{VC Mode Line}). |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
1630 |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
1631 Here is what @kbd{C-x v v} does when using a merging-based system: |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
1632 |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
1633 @itemize @bullet |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
1634 @item |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
1635 If the work file is the same as in the repository, it does nothing. |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
1636 |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
1637 @item |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
1638 If you have not changed the work file, but some other user has checked |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
1639 in changes to the repository, @kbd{C-x v v} merges those changes into |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
1640 the work file. |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
1641 |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
1642 @item |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
1643 If you have made modifications to the work file, @kbd{C-x v v} |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
1644 attempts to check in your changes. To do this, Emacs first reads the |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
1645 log entry for the new revision (@pxref{Log Buffer}). If some other |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
1646 user has checked in changes to the repository since you last checked |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
1647 it out, the checkin fails. In that case, type @kbd{C-x v v} again to |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
1648 merge those changes into your own work file; this puts the work file |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
1649 into a ``conflicted'' state. Type @kbd{C-x v v} to clear the |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
1650 ``conflicted'' state; VC then regards the file as up-to-date and |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
1651 modified, and you can try to check it in again. |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
1652 |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
1653 To pick up any recent changes from the repository @emph{without} |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
1654 trying to commit your own changes, type @kbd{C-x v m @key{RET}}. |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
1655 @xref{Merging}. |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
1656 @end itemize |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
1657 |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
1658 These rules also apply when you use RCS in its ``non-locking'' mode, |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
1659 except that changes will not be automatically merged from the |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
1660 repository. Nothing informs you if another user has checked in |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
1661 changes in the same file since you began editing it; when you check in |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
1662 your revision, his changes are removed (however, they remain in the |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
1663 repository and are thus not irrevocably lost). Therefore, you must |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
1664 verify that the current revision is unchanged before checking in your |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
1665 changes. In addition, locking is possible with RCS even in this mode: |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
1666 @kbd{C-x v v} with an unmodified file locks the file, just as it does |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
1667 with RCS in its normal locking mode (@pxref{VC With A Locking VCS}). |
84239 | 1668 |
85236
7d608cb0bc46
Capitalize node names according to convention.
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85176
diff
changeset
|
1669 @node VC With A Locking VCS |
84239 | 1670 @subsubsection Basic Version Control with Locking |
1671 | |
99002
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
1672 Under a locking-based version control system (such as SCCS, and RCS |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
1673 in its default mode), @kbd{C-x v v} does the following: |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
1674 |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
1675 @itemize @bullet |
84239 | 1676 @item |
99002
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
1677 If the file is not locked, @kbd{C-x v v} locks it, and makes it |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
1678 writable so that you can change it. |
84239 | 1679 |
1680 @item | |
99002
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
1681 If the file is locked by you, and contains changes, @kbd{C-x v v} |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
1682 checks in the changes. In order to do this, it first reads the log |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
1683 entry for the new revision. @xref{Log Buffer}. |
84239 | 1684 |
1685 @item | |
1686 If the file is locked by you, but you have not changed it since you | |
99002
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
1687 locked it, @kbd{C-x v v} releases the lock and makes the file |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
1688 read-only again. |
84239 | 1689 |
1690 @item | |
1691 If the file is locked by some other user, @kbd{C-x v v} asks you whether | |
1692 you want to ``steal the lock'' from that user. If you say yes, the file | |
1693 becomes locked by you, but a message is sent to the person who had | |
1694 formerly locked the file, to inform him of what has happened. | |
1695 @end itemize | |
1696 | |
1697 These rules also apply when you use CVS in locking mode, except | |
1698 that there is no such thing as stealing a lock. | |
1699 | |
1700 @node Advanced C-x v v | |
1701 @subsubsection Advanced Control in @kbd{C-x v v} | |
1702 | |
85152
a0d3d8180a58
Revise version-control portions of the manual to include
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85139
diff
changeset
|
1703 @cindex revision ID to check in/out |
84239 | 1704 When you give a prefix argument to @code{vc-next-action} (@kbd{C-u |
1705 C-x v v}), it still performs the next logical version control | |
1706 operation, but accepts additional arguments to specify precisely how | |
1707 to do the operation. | |
1708 | |
1709 @itemize @bullet | |
1710 @item | |
85139
8ba0e30716a5
Terminology cleanup.
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85135
diff
changeset
|
1711 If the file is modified (or locked), you can specify the revision ID |
8ba0e30716a5
Terminology cleanup.
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85135
diff
changeset
|
1712 to use for the new version that you check in. This is one way |
84239 | 1713 to create a new branch (@pxref{Branches}). |
1714 | |
1715 @item | |
1716 If the file is not modified (and unlocked), you can specify the | |
85139
8ba0e30716a5
Terminology cleanup.
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85135
diff
changeset
|
1717 revision to select; this lets you start working from an older |
8ba0e30716a5
Terminology cleanup.
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85135
diff
changeset
|
1718 revision, or on another branch. If you do not enter any revision, |
8ba0e30716a5
Terminology cleanup.
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85135
diff
changeset
|
1719 that takes you to the highest (``head'') revision on the current |
8ba0e30716a5
Terminology cleanup.
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85135
diff
changeset
|
1720 branch; therefore @kbd{C-u C-x v v @key{RET}} is a convenient way to |
8ba0e30716a5
Terminology cleanup.
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85135
diff
changeset
|
1721 get the latest version of a file from the repository. |
84239 | 1722 |
1723 @item | |
1724 @cindex specific version control system | |
85152
a0d3d8180a58
Revise version-control portions of the manual to include
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85139
diff
changeset
|
1725 Instead of the revision ID, you can also specify the name of a |
84239 | 1726 version control system. This is useful when one file is being managed |
1727 with two version control systems at the same time | |
1728 @iftex | |
1729 (@pxref{Local Version Control,,,emacs-xtra, Specialized Emacs | |
1730 Features}). | |
1731 @end iftex | |
1732 @ifnottex | |
1733 (@pxref{Local Version Control}). | |
1734 @end ifnottex | |
1735 | |
1736 @end itemize | |
1737 | |
1738 @node Log Buffer | |
1739 @subsubsection Features of the Log Entry Buffer | |
1740 | |
99002
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
1741 When you check in changes, Emacs pops up a buffer called |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
1742 @samp{*VC-Log*} for you to enter a log entry. |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
1743 |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
1744 After you have finished editing the log message, type @kbd{C-c C-c} |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
1745 to exit the buffer and commit the change. |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
1746 |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
1747 @findex log-edit-show-files |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
1748 @findex log-edit-show-diff |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
1749 In the @samp{*VC-Log*} buffer, typing @kbd{C-c C-f} |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
1750 (@code{log-edit-show-files}) displays a list of files in the VC |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
1751 fileset you are committing. If you called @kbd{C-x v v} directly from |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
1752 a work file, the VC fileset consists of that single file, so this |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
1753 command is not very useful. If you called @kbd{C-x v v} from a VC |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
1754 directory buffer, the VC fileset may consist of multiple files |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
1755 (@pxref{VC Directory Mode}). |
84239 | 1756 |
1757 @findex log-edit-insert-changelog | |
99002
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
1758 Type @kbd{C-c C-d} (@code{log-edit-show-diff}) to show a ``diff'' of |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
1759 the changes you have made (i.e., the differences between the work file |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
1760 and the repository revision from which you started editing the file). |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
1761 The diff is displayed in a special buffer in another window. |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
1762 @xref{Comparing Files}. |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
1763 |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
1764 If you have written an entry in the @file{ChangeLog} (@pxref{Change |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
1765 Log}), type @kbd{C-c C-a} (@code{log-edit-insert-changelog}) to pull |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
1766 it into the @samp{*VC-Log*} buffer. If the topmost item in the |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
1767 @file{ChangeLog} was made under your user name on the current date, |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
1768 this command searches that item for entries that match the file(s) to |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
1769 be committed; if found, these entries are inserted. |
84239 | 1770 @iftex |
1771 @xref{Change Logs and VC,,,emacs-xtra, Specialized Emacs Features}, | |
1772 @end iftex | |
1773 @ifnottex | |
1774 @xref{Change Logs and VC}, | |
1775 @end ifnottex | |
1776 for the opposite way of working---generating ChangeLog entries from | |
1777 the revision control log. | |
1778 | |
99002
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
1779 To abort a check-in, just @strong{don't} type @kbd{C-c C-c} in that |
84239 | 1780 buffer. You can switch buffers and do other editing. As long as you |
1781 don't try to check in another file, the entry you were editing remains | |
99002
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
1782 in the @samp{*VC-Log*} buffer, and you can go back to that buffer at |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
1783 any time to complete the check-in. |
84239 | 1784 |
1785 If you change several source files for the same reason, it is often | |
85133
87df82f093bd
New VC command docs for the Emacs manual.
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85123
diff
changeset
|
1786 convenient to specify the same log entry for many of the files. (This |
87df82f093bd
New VC command docs for the Emacs manual.
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85123
diff
changeset
|
1787 is the normal way to do things on a changeset-oriented system, where |
87df82f093bd
New VC command docs for the Emacs manual.
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85123
diff
changeset
|
1788 comments are attached to changesets rather than the history of |
99002
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
1789 individual files.) The most convenient way to do this is to mark all |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
1790 the files in VC Directory Mode and check in from there; the log buffer |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
1791 will carry the fileset information with it and do a group commit when |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
1792 you type @kbd{C-c C-c}. |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
1793 |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
1794 You can also browse the history of previous log entries to duplicate |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
1795 a checkin comment. This can be useful when you want several files to |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
1796 have checkin comments that vary only slightly from each other. The |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
1797 commands @kbd{M-n}, @kbd{M-p}, @kbd{M-s} and @kbd{M-r} for doing this |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
1798 work just like the minibuffer history commands (except that these |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
1799 versions are used outside the minibuffer). |
85063
4cdaedc4a269
More manual updates and additions bringing it current with modern
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85061
diff
changeset
|
1800 |
84239 | 1801 @vindex vc-log-mode-hook |
99002
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
1802 Each time you check in a change, the log entry buffer is put into VC |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
1803 Log Edit mode, which involves running two hooks: @code{text-mode-hook} |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
1804 and @code{vc-log-mode-hook}. @xref{Hooks}. |
84239 | 1805 |
85139
8ba0e30716a5
Terminology cleanup.
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85135
diff
changeset
|
1806 @node Old Revisions |
8ba0e30716a5
Terminology cleanup.
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85135
diff
changeset
|
1807 @subsection Examining And Comparing Old Revisions |
84239 | 1808 |
1809 One of the convenient features of version control is the ability | |
85139
8ba0e30716a5
Terminology cleanup.
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85135
diff
changeset
|
1810 to examine any revision of a file, or compare two revisions. |
84239 | 1811 |
1812 @table @kbd | |
85139
8ba0e30716a5
Terminology cleanup.
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85135
diff
changeset
|
1813 @item C-x v ~ @var{revision} @key{RET} |
8ba0e30716a5
Terminology cleanup.
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85135
diff
changeset
|
1814 Examine revision @var{revision} of the visited file, in a buffer of its |
84239 | 1815 own. |
1816 | |
1817 @item C-x v = | |
85152
a0d3d8180a58
Revise version-control portions of the manual to include
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85139
diff
changeset
|
1818 Compare the buffer contents associated with the current |
a0d3d8180a58
Revise version-control portions of the manual to include
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85139
diff
changeset
|
1819 fileset with the working revision(s) from which you started editing. |
85133
87df82f093bd
New VC command docs for the Emacs manual.
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85123
diff
changeset
|
1820 |
87df82f093bd
New VC command docs for the Emacs manual.
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85123
diff
changeset
|
1821 @item C-u C-x v = @key{RET} @var{oldvers} @key{RET} @var{newvers} @key{RET} |
85139
8ba0e30716a5
Terminology cleanup.
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85135
diff
changeset
|
1822 Compare the specified two repository revisions of the current fileset. |
84239 | 1823 |
1824 @item C-x v g | |
99002
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
1825 Display an annotated version of the file: for each line, show the |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
1826 latest revision in which it was modified. |
84239 | 1827 @end table |
1828 | |
85139
8ba0e30716a5
Terminology cleanup.
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85135
diff
changeset
|
1829 @findex vc-revision-other-window |
84239 | 1830 @kindex C-x v ~ |
99002
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
1831 To examine an old revision, visit the work file and type @kbd{C-x v |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
1832 ~ @var{revision} @key{RET}} (@code{vc-revision-other-window}). Here, |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
1833 @var{revision} is either the desired revision ID (@pxref{VCS |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
1834 Concepts}), or the name of a tag or branch |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
1835 @iftex |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
1836 (@pxref{Tags,,,emacs-xtra, Specialized Emacs Features}). |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
1837 @end iftex |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
1838 @ifnottex |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
1839 (@pxref{Tags}). |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
1840 @end ifnottex |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
1841 This command puts the text of the old revision in a file named |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
1842 @file{@var{filename}.~@var{revision}~}, and visits it in its own |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
1843 buffer in a separate window. |
84239 | 1844 |
1845 @findex vc-diff | |
1846 @kindex C-x v = | |
99002
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
1847 @kbd{C-x v =} (@code{vc-diff}) compares the current buffer contents |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
1848 of each file in the current VC fileset (saving them if necessary) with |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
1849 the repository revision from which you started editing. Note that the |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
1850 latter may or may not be the latest revision of the file(s). The diff |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
1851 is displayed in a special buffer in another window. @xref{Comparing |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
1852 Files}. |
85133
87df82f093bd
New VC command docs for the Emacs manual.
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85123
diff
changeset
|
1853 |
87df82f093bd
New VC command docs for the Emacs manual.
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85123
diff
changeset
|
1854 @findex vc-diff |
87df82f093bd
New VC command docs for the Emacs manual.
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85123
diff
changeset
|
1855 @kindex C-u C-x v = |
99002
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
1856 To compare two arbitrary revisions of the current VC fileset, call |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
1857 @code{vc-diff} with a prefix argument: @kbd{C-u C-x v =}. This |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
1858 prompts for two revision IDs, using the minibuffer, and displays the |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
1859 diff in a special buffer in another window. Instead of providing a |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
1860 revision ID, you can give an empty input, which specifies the current |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
1861 contents of the work file; or a tag or branch name |
84239 | 1862 @iftex |
99002
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
1863 (@pxref{Tags,,,emacs-xtra, Specialized Emacs Features}). |
84239 | 1864 @end iftex |
1865 @ifnottex | |
99002
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
1866 (@pxref{Tags}). |
84239 | 1867 @end ifnottex |
99002
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
1868 If your version control system is file-based (e.g. CVS) rather than |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
1869 changeset-based (Subversion, GNU Arch, git, Mercurial), supplying a |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
1870 revision ID for a multi-file fileset (as opposed to a symbolic tag |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
1871 name) is unlikely to return diffs that are connected in any meaningful |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
1872 way. |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
1873 |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
1874 If you invoke @kbd{C-x v =} or @kbd{C-u C-x v =} from a buffer that |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
1875 is neither visiting a version-controlled file nor a VC directory |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
1876 buffer, these commands generate a diff of all registered files in the |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
1877 current directory and its subdirectories. |
84239 | 1878 |
1879 @vindex vc-diff-switches | |
1880 @vindex vc-rcs-diff-switches | |
1881 @kbd{C-x v =} works by running a variant of the @code{diff} utility | |
1882 designed to work with the version control system in use. When you | |
1883 invoke @code{diff} this way, in addition to the options specified by | |
1884 @code{diff-switches} (@pxref{Comparing Files}), it receives those | |
1885 specified by @code{vc-diff-switches}, plus those specified for the | |
1886 specific back end by @code{vc-@var{backend}-diff-switches}. For | |
99002
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
1887 instance, when the version control back end is CVS, @code{diff} uses |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
1888 the options in @code{vc-cvs-diff-switches}. The |
84239 | 1889 @samp{vc@dots{}diff-switches} variables are @code{nil} by default. |
1890 | |
1891 The buffer produced by @kbd{C-x v =} supports the commands of | |
1892 Compilation mode (@pxref{Compilation Mode}), such as @kbd{C-x `} and | |
1893 @kbd{C-c C-c}, in both the ``old'' and ``new'' text, and they always | |
1894 find the corresponding locations in the current work file. (Older | |
85139
8ba0e30716a5
Terminology cleanup.
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85135
diff
changeset
|
1895 revisions are not, in general, present as files on your disk.) |
84239 | 1896 |
1897 @findex vc-annotate | |
1898 @kindex C-x v g | |
1899 For some back ends, you can display the file @dfn{annotated} with | |
99002
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
1900 per-line revision information, by typing @kbd{C-x v g} |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
1901 (@code{vc-annotate}). This creates a new buffer (the ``annotate |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
1902 buffer'') displaying the file's text, with each part colored to show |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
1903 how old it is. Text colored red is new, blue means old, and |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
1904 intermediate colors indicate intermediate ages. By default, the color |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
1905 is scaled over the full range of ages, such that the oldest changes |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
1906 are blue, and the newest changes are red. |
84239 | 1907 |
86368
319d5c4e0f9c
(Log Buffer): Fix typos; small rewording.
Thien-Thi Nguyen <ttn@gnuvola.org>
parents:
86366
diff
changeset
|
1908 When you give a prefix argument to this command, Emacs reads two |
319d5c4e0f9c
(Log Buffer): Fix typos; small rewording.
Thien-Thi Nguyen <ttn@gnuvola.org>
parents:
86366
diff
changeset
|
1909 arguments using the minibuffer: the ID of which revision to display and |
84239 | 1910 annotate (instead of the current file contents), and the time span in |
1911 days the color range should cover. | |
1912 | |
1913 From the annotate buffer, these and other color scaling options are | |
1914 available from the @samp{VC-Annotate} menu. In this buffer, you can | |
1915 also use the following keys to browse the annotations of past revisions, | |
1916 view diffs, or view log entries: | |
1917 | |
1918 @table @kbd | |
97331
3b4f09195a23
(Old Revisions): Update the keys used by vc-annotate and
Dan Nicolaescu <dann@ics.uci.edu>
parents:
96962
diff
changeset
|
1919 @item p |
84239 | 1920 Annotate the previous revision, that is to say, the revision before |
1921 the one currently annotated. A numeric prefix argument is a repeat | |
97331
3b4f09195a23
(Old Revisions): Update the keys used by vc-annotate and
Dan Nicolaescu <dann@ics.uci.edu>
parents:
96962
diff
changeset
|
1922 count, so @kbd{C-u 10 p} would take you back 10 revisions. |
3b4f09195a23
(Old Revisions): Update the keys used by vc-annotate and
Dan Nicolaescu <dann@ics.uci.edu>
parents:
96962
diff
changeset
|
1923 |
3b4f09195a23
(Old Revisions): Update the keys used by vc-annotate and
Dan Nicolaescu <dann@ics.uci.edu>
parents:
96962
diff
changeset
|
1924 @item n |
84239 | 1925 Annotate the next revision---the one after the revision currently |
1926 annotated. A numeric prefix argument is a repeat count. | |
1927 | |
97331
3b4f09195a23
(Old Revisions): Update the keys used by vc-annotate and
Dan Nicolaescu <dann@ics.uci.edu>
parents:
96962
diff
changeset
|
1928 @item j |
84239 | 1929 Annotate the revision indicated by the current line. |
1930 | |
97331
3b4f09195a23
(Old Revisions): Update the keys used by vc-annotate and
Dan Nicolaescu <dann@ics.uci.edu>
parents:
96962
diff
changeset
|
1931 @item a |
84239 | 1932 Annotate the revision before the one indicated by the current line. |
1933 This is useful to see the state the file was in before the change on | |
1934 the current line was made. | |
1935 | |
97331
3b4f09195a23
(Old Revisions): Update the keys used by vc-annotate and
Dan Nicolaescu <dann@ics.uci.edu>
parents:
96962
diff
changeset
|
1936 @item f |
3b4f09195a23
(Old Revisions): Update the keys used by vc-annotate and
Dan Nicolaescu <dann@ics.uci.edu>
parents:
96962
diff
changeset
|
1937 Show in a buffer the file revision indicated by the current line. |
3b4f09195a23
(Old Revisions): Update the keys used by vc-annotate and
Dan Nicolaescu <dann@ics.uci.edu>
parents:
96962
diff
changeset
|
1938 |
3b4f09195a23
(Old Revisions): Update the keys used by vc-annotate and
Dan Nicolaescu <dann@ics.uci.edu>
parents:
96962
diff
changeset
|
1939 @item d |
84239 | 1940 Display the diff between the current line's revision and the previous |
1941 revision. This is useful to see what the current line's revision | |
1942 actually changed in the file. | |
1943 | |
97331
3b4f09195a23
(Old Revisions): Update the keys used by vc-annotate and
Dan Nicolaescu <dann@ics.uci.edu>
parents:
96962
diff
changeset
|
1944 @item D |
3b4f09195a23
(Old Revisions): Update the keys used by vc-annotate and
Dan Nicolaescu <dann@ics.uci.edu>
parents:
96962
diff
changeset
|
1945 Display the diff between the current line's revision and the previous |
3b4f09195a23
(Old Revisions): Update the keys used by vc-annotate and
Dan Nicolaescu <dann@ics.uci.edu>
parents:
96962
diff
changeset
|
1946 revision for all files in the changeset (for VC systems that support |
3b4f09195a23
(Old Revisions): Update the keys used by vc-annotate and
Dan Nicolaescu <dann@ics.uci.edu>
parents:
96962
diff
changeset
|
1947 changesets). This is useful to see what the current line's revision |
3b4f09195a23
(Old Revisions): Update the keys used by vc-annotate and
Dan Nicolaescu <dann@ics.uci.edu>
parents:
96962
diff
changeset
|
1948 actually changed in the tree. |
3b4f09195a23
(Old Revisions): Update the keys used by vc-annotate and
Dan Nicolaescu <dann@ics.uci.edu>
parents:
96962
diff
changeset
|
1949 |
3b4f09195a23
(Old Revisions): Update the keys used by vc-annotate and
Dan Nicolaescu <dann@ics.uci.edu>
parents:
96962
diff
changeset
|
1950 @item l |
84239 | 1951 Show the log of the current line's revision. This is useful to see |
1952 the author's description of the changes in the revision on the current | |
1953 line. | |
1954 | |
97331
3b4f09195a23
(Old Revisions): Update the keys used by vc-annotate and
Dan Nicolaescu <dann@ics.uci.edu>
parents:
96962
diff
changeset
|
1955 @item w |
85139
8ba0e30716a5
Terminology cleanup.
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85135
diff
changeset
|
1956 Annotate the working revision--the one you are editing. If you used |
97331
3b4f09195a23
(Old Revisions): Update the keys used by vc-annotate and
Dan Nicolaescu <dann@ics.uci.edu>
parents:
96962
diff
changeset
|
1957 @kbd{p} and @kbd{n} to browse to other revisions, use this key to |
85139
8ba0e30716a5
Terminology cleanup.
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85135
diff
changeset
|
1958 return to your working revision. |
97331
3b4f09195a23
(Old Revisions): Update the keys used by vc-annotate and
Dan Nicolaescu <dann@ics.uci.edu>
parents:
96962
diff
changeset
|
1959 |
3b4f09195a23
(Old Revisions): Update the keys used by vc-annotate and
Dan Nicolaescu <dann@ics.uci.edu>
parents:
96962
diff
changeset
|
1960 @item v |
3b4f09195a23
(Old Revisions): Update the keys used by vc-annotate and
Dan Nicolaescu <dann@ics.uci.edu>
parents:
96962
diff
changeset
|
1961 Toggle the annotation visibility. This is useful for looking just at |
3b4f09195a23
(Old Revisions): Update the keys used by vc-annotate and
Dan Nicolaescu <dann@ics.uci.edu>
parents:
96962
diff
changeset
|
1962 the file contents without distraction from the annotations. |
84239 | 1963 @end table |
1964 | |
1965 @node Secondary VC Commands | |
1966 @subsection The Secondary Commands of VC | |
1967 | |
99002
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
1968 This section explains the secondary commands of VC. |
84239 | 1969 |
1970 @menu | |
1971 * Registering:: Putting a file under version control. | |
1972 * VC Status:: Viewing the VC status of files. | |
1973 * VC Undo:: Canceling changes before or after check-in. | |
1974 @end menu | |
1975 | |
1976 @node Registering | |
1977 @subsubsection Registering a File for Version Control | |
1978 | |
1979 @kindex C-x v i | |
1980 @findex vc-register | |
1981 You can put any file under version control by simply visiting it, and | |
1982 then typing @w{@kbd{C-x v i}} (@code{vc-register}). | |
1983 | |
1984 @table @kbd | |
1985 @item C-x v i | |
1986 Register the visited file for version control. | |
1987 @end table | |
1988 | |
1989 To register the file, Emacs must choose which version control system | |
1990 to use for it. If the file's directory already contains files | |
1991 registered in a version control system, Emacs uses that system. If | |
1992 there is more than one system in use for a directory, Emacs uses the | |
1993 one that appears first in @code{vc-handled-backends} | |
1994 @iftex | |
1995 (@pxref{Customizing VC,,,emacs-xtra, Specialized Emacs Features}). | |
1996 @end iftex | |
1997 @ifnottex | |
1998 (@pxref{Customizing VC}). | |
1999 @end ifnottex | |
2000 On the other hand, if there are no files already registered, Emacs uses | |
2001 the first system from @code{vc-handled-backends} that could register | |
2002 the file (for example, you cannot register a file under CVS if its | |
2003 directory is not already part of a CVS tree); with the default value | |
2004 of @code{vc-handled-backends}, this means that Emacs uses RCS in this | |
2005 situation. | |
2006 | |
2007 If locking is in use, @kbd{C-x v i} leaves the file unlocked and | |
2008 read-only. Type @kbd{C-x v v} if you wish to start editing it. After | |
2009 registering a file with CVS, you must subsequently commit the initial | |
85139
8ba0e30716a5
Terminology cleanup.
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85135
diff
changeset
|
2010 revision by typing @kbd{C-x v v}. Until you do that, the revision ID |
84239 | 2011 appears as @samp{@@@@} in the mode line. |
2012 | |
85139
8ba0e30716a5
Terminology cleanup.
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85135
diff
changeset
|
2013 @vindex vc-default-init-revision |
85152
a0d3d8180a58
Revise version-control portions of the manual to include
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85139
diff
changeset
|
2014 @cindex initial revision ID to register |
a0d3d8180a58
Revise version-control portions of the manual to include
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85139
diff
changeset
|
2015 The default initial revision ID for a newly registered file |
a0d3d8180a58
Revise version-control portions of the manual to include
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85139
diff
changeset
|
2016 varies by what VCS you are using; normally it will be 1.1 on VCSes |
a0d3d8180a58
Revise version-control portions of the manual to include
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85139
diff
changeset
|
2017 that use dot-pair revision IDs and 1 on VCSes that use monotonic IDs. |
a0d3d8180a58
Revise version-control portions of the manual to include
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85139
diff
changeset
|
2018 You can specify a different default by setting the variable |
a0d3d8180a58
Revise version-control portions of the manual to include
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85139
diff
changeset
|
2019 @code{vc-default-init-revision}, or you can give @kbd{C-x v i} a |
a0d3d8180a58
Revise version-control portions of the manual to include
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85139
diff
changeset
|
2020 numeric argument; then it reads the initial revision ID for this |
a0d3d8180a58
Revise version-control portions of the manual to include
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85139
diff
changeset
|
2021 particular file using the minibuffer. |
84239 | 2022 |
2023 @vindex vc-initial-comment | |
2024 If @code{vc-initial-comment} is non-@code{nil}, @kbd{C-x v i} reads an | |
2025 initial comment to describe the purpose of this source file. Reading | |
2026 the initial comment works like reading a log entry (@pxref{Log Buffer}). | |
2027 | |
2028 @node VC Status | |
2029 @subsubsection VC Status Commands | |
2030 | |
2031 @table @kbd | |
2032 @item C-x v l | |
85139
8ba0e30716a5
Terminology cleanup.
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85135
diff
changeset
|
2033 Display revision control state and change history. |
84239 | 2034 @end table |
2035 | |
2036 @kindex C-x v l | |
2037 @findex vc-print-log | |
85139
8ba0e30716a5
Terminology cleanup.
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85135
diff
changeset
|
2038 To view the detailed revision control status and history of a file, |
99002
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
2039 type @kbd{C-x v l} (@code{vc-print-log}). This pops up a special |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
2040 buffer named @samp{*vc-change-log*}, in a new window, that displays |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
2041 the history of changes to the current file, including the text of the |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
2042 log entries. The point is centered at the revision of the file that |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
2043 is currently being visited. |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
2044 |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
2045 In the @samp{*vc-change-log*} buffer, you can use the following keys |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
2046 to move between the logs of revisions and of files, to view past |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
2047 revisions, to modify change comments, to view annotations and to view |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
2048 diffs: |
84239 | 2049 |
2050 @table @kbd | |
2051 @item p | |
2052 Move to the previous revision-item in the buffer. (Revision entries in the log | |
2053 buffer are usually in reverse-chronological order, so the previous | |
2054 revision-item usually corresponds to a newer revision.) A numeric | |
2055 prefix argument is a repeat count. | |
2056 | |
2057 @item n | |
2058 Move to the next revision-item (which most often corresponds to the | |
2059 previous revision of the file). A numeric prefix argument is a repeat | |
2060 count. | |
2061 | |
2062 @item P | |
2063 Move to the log of the previous file, when the logs of multiple files | |
99002
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
2064 are in the log buffer (@pxref{VC Directory Mode}). Otherwise, just |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
2065 move to the beginning of the log. A numeric prefix argument is a |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
2066 repeat count, so @kbd{C-u 10 P} would move backward 10 files. |
84239 | 2067 |
2068 @item N | |
2069 Move to the log of the next file, when the logs of multiple files are | |
99002
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
2070 in the log buffer (@pxref{VC Directory Mode}). It also takes a |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
2071 numeric prefix argument as a repeat count. |
84239 | 2072 |
97331
3b4f09195a23
(Old Revisions): Update the keys used by vc-annotate and
Dan Nicolaescu <dann@ics.uci.edu>
parents:
96962
diff
changeset
|
2073 @item a |
3b4f09195a23
(Old Revisions): Update the keys used by vc-annotate and
Dan Nicolaescu <dann@ics.uci.edu>
parents:
96962
diff
changeset
|
2074 Annotate the revision indicated by the current line. |
3b4f09195a23
(Old Revisions): Update the keys used by vc-annotate and
Dan Nicolaescu <dann@ics.uci.edu>
parents:
96962
diff
changeset
|
2075 |
3b4f09195a23
(Old Revisions): Update the keys used by vc-annotate and
Dan Nicolaescu <dann@ics.uci.edu>
parents:
96962
diff
changeset
|
2076 @item e |
3b4f09195a23
(Old Revisions): Update the keys used by vc-annotate and
Dan Nicolaescu <dann@ics.uci.edu>
parents:
96962
diff
changeset
|
2077 Modify the change comment displayed at point. Note that not all VC |
3b4f09195a23
(Old Revisions): Update the keys used by vc-annotate and
Dan Nicolaescu <dann@ics.uci.edu>
parents:
96962
diff
changeset
|
2078 systems support modifying change comments. |
3b4f09195a23
(Old Revisions): Update the keys used by vc-annotate and
Dan Nicolaescu <dann@ics.uci.edu>
parents:
96962
diff
changeset
|
2079 |
84239 | 2080 @item f |
2081 Visit the revision indicated at the current line, like typing @kbd{C-x | |
85152
a0d3d8180a58
Revise version-control portions of the manual to include
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85139
diff
changeset
|
2082 v ~} and specifying this revision's ID (@pxref{Old Revisions}). |
84239 | 2083 |
2084 @item d | |
2085 Display the diff (@pxref{Comparing Files}) between the revision | |
2086 indicated at the current line and the next earlier revision. This is | |
97331
3b4f09195a23
(Old Revisions): Update the keys used by vc-annotate and
Dan Nicolaescu <dann@ics.uci.edu>
parents:
96962
diff
changeset
|
2087 useful to see what actually changed in the file when the revision |
3b4f09195a23
(Old Revisions): Update the keys used by vc-annotate and
Dan Nicolaescu <dann@ics.uci.edu>
parents:
96962
diff
changeset
|
2088 indicated on the current line was committed. |
3b4f09195a23
(Old Revisions): Update the keys used by vc-annotate and
Dan Nicolaescu <dann@ics.uci.edu>
parents:
96962
diff
changeset
|
2089 |
3b4f09195a23
(Old Revisions): Update the keys used by vc-annotate and
Dan Nicolaescu <dann@ics.uci.edu>
parents:
96962
diff
changeset
|
2090 @item D |
3b4f09195a23
(Old Revisions): Update the keys used by vc-annotate and
Dan Nicolaescu <dann@ics.uci.edu>
parents:
96962
diff
changeset
|
2091 Display the changeset diff (@pxref{Comparing Files}) between the |
3b4f09195a23
(Old Revisions): Update the keys used by vc-annotate and
Dan Nicolaescu <dann@ics.uci.edu>
parents:
96962
diff
changeset
|
2092 revision indicated at the current line and the next earlier revision. |
3b4f09195a23
(Old Revisions): Update the keys used by vc-annotate and
Dan Nicolaescu <dann@ics.uci.edu>
parents:
96962
diff
changeset
|
2093 This is useful to see all the changes to all files that the revision |
3b4f09195a23
(Old Revisions): Update the keys used by vc-annotate and
Dan Nicolaescu <dann@ics.uci.edu>
parents:
96962
diff
changeset
|
2094 indicated on the current line did when it was committed. |
84239 | 2095 @end table |
2096 | |
2097 @node VC Undo | |
2098 @subsubsection Undoing Version Control Actions | |
2099 | |
2100 @table @kbd | |
2101 @item C-x v u | |
85139
8ba0e30716a5
Terminology cleanup.
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85135
diff
changeset
|
2102 Revert the buffer and the file to the working revision from which you started |
84239 | 2103 editing the file. |
2104 | |
2105 @item C-x v c | |
2106 Remove the last-entered change from the master for the visited file. | |
2107 This undoes your last check-in. | |
2108 @end table | |
2109 | |
2110 @kindex C-x v u | |
2111 @findex vc-revert-buffer | |
2112 If you want to discard your current set of changes and revert to the | |
99002
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
2113 working revision from which you started editing the file, use @kbd{C-x |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
2114 v u} (@code{vc-revert-buffer}). If the version control system is |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
2115 locking-based, this leaves the file unlocked, and you must lock it |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
2116 again before making new changes. @kbd{C-x v u} requires confirmation, |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
2117 unless it sees that you haven't made any changes with respect to the |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
2118 master copy of the working revision. |
84239 | 2119 |
2120 @kbd{C-x v u} is also the command to unlock a file if you lock it and | |
2121 then decide not to change it. | |
2122 | |
2123 @kindex C-x v c | |
85133
87df82f093bd
New VC command docs for the Emacs manual.
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85123
diff
changeset
|
2124 @findex vc-rollback |
84239 | 2125 To cancel a change that you already checked in, use @kbd{C-x v c} |
85133
87df82f093bd
New VC command docs for the Emacs manual.
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85123
diff
changeset
|
2126 (@code{vc-rollback}). This command discards all record of the most |
85139
8ba0e30716a5
Terminology cleanup.
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85135
diff
changeset
|
2127 recent checked-in revision, but only if your work file corresponds to |
99002
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
2128 that revision---you cannot use @kbd{C-x v c} to cancel a revision that |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
2129 is not the latest on its branch. Note that many version control |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
2130 systems do not support rollback at all; this command is something of a |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
2131 historical relic. |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
2132 |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
2133 @node VC Directory Mode |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
2134 @subsection VC Directory Mode |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
2135 |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
2136 @kindex C-x v d |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
2137 @findex vc-dir |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
2138 When you are working on a large program, it is often useful to find |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
2139 out which files have changed within an entire directory tree, or to |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
2140 view the status of all files under version control at once, and to |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
2141 perform version control operations on collections of files. You can |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
2142 use the command @kbd{C-x v d} (@code{vc-dir}) to make a directory |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
2143 listing that includes only files relevant for version control. This |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
2144 creates a @dfn{VC Directory buffer} and displays it in a separate |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
2145 window. |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
2146 |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
2147 @cindex PCL-CVS |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
2148 @pindex cvs |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
2149 @cindex CVS directory mode |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
2150 The VC Directory buffer described here works with all the version |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
2151 control systems that VC supports. Another more powerful facility, |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
2152 designed specifically for CVS, is called PCL-CVS. @xref{Top, , About |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
2153 PCL-CVS, pcl-cvs, PCL-CVS --- The Emacs Front-End to CVS}. |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
2154 |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
2155 The VC Directory buffer contains a list of version-controlled files |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
2156 in the current directory and its subdirectories. Files which are |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
2157 up-to-date (have no local differences from the repository copy) are |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
2158 omitted; if all files in a directory are up-to-date, the directory is |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
2159 omitted as well. (However, the directory in which @code{vc-dir} was |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
2160 run will always be shown as @file{./}.) There is an exception to this |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
2161 rule: if VC mode detects that a file has changed to an up-to-date |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
2162 state since you last looked at it, that file and its state are shown. |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
2163 |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
2164 If a directory uses more that one version control system, you can |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
2165 select which system to use for the @code{vc-dir} command by invoking |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
2166 @code{vc-dir} with a prefix argument: @kbd{C-u C-x v d}. |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
2167 |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
2168 The line for an individual file shows the version control state of |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
2169 the file. Under RCS and SCCS, the name of the user locking the file |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
2170 is shown; under CVS, an abbreviated version of the @samp{cvs status} |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
2171 output is used. Here is an example using CVS: |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
2172 |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
2173 @smallexample |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
2174 @group |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
2175 ./ |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
2176 modified file1.c |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
2177 needs-update file2.c |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
2178 needs-merge file3.c |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
2179 @end group |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
2180 @end smallexample |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
2181 |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
2182 @noindent |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
2183 In this example, @samp{file1.c} is modified with respect to the |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
2184 repository, and @samp{file2.c} is not. @samp{file3.c} is modified, |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
2185 but other changes have also been checked in to the repository---you |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
2186 need to merge them with the work file before you can check it in. |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
2187 |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
2188 @vindex vc-stay-local |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
2189 @vindex vc-cvs-stay-local |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
2190 In the above, if the repository were on a remote machine, VC only |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
2191 contacts it when the variable @code{vc-stay-local} (or |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
2192 @code{vc-cvs-stay-local}) is nil (@pxref{CVS Options}). This is |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
2193 because access to the repository may be slow, or you may be working |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
2194 offline and not have access to the repository at all. As a |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
2195 consequence, VC would not be able to tell you that @samp{file3.c} is |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
2196 in the ``merge'' state; you would learn that only when you try to |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
2197 check-in your modified copy of the file, or use a command such as |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
2198 @kbd{C-x v m}. |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
2199 |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
2200 In practice, this is not a problem because CVS handles this case |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
2201 consistently whenever it arises. In VC, you'll simply get prompted to |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
2202 merge the remote changes into your work file first. The benefits of |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
2203 less network communication usually outweigh the disadvantage of not |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
2204 seeing remote changes immediately. |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
2205 |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
2206 @vindex vc-directory-exclusion-list |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
2207 When a VC directory displays subdirectories it omits some that |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
2208 should never contain any files under version control. By default, |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
2209 this includes Version Control subdirectories such as @samp{RCS} and |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
2210 @samp{CVS}; you can customize this by setting the variable |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
2211 @code{vc-directory-exclusion-list}. |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
2212 |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
2213 @menu |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
2214 * VC Directory Commands:: Commands to use in a VC directory buffer. |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
2215 @end menu |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
2216 |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
2217 @node VC Directory Commands |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
2218 @subsubsection VC Directory Commands |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
2219 |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
2220 VC Directory mode has a full set of navigation and marking commands |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
2221 for picking out filesets. Some of these are also available in a |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
2222 context menu invoked by the @kbd{mouse-2} button. |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
2223 |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
2224 Up- and down-arrow keys move in the buffer; @kbd{n} and @kbd{p} also |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
2225 move vertically as in other list-browsing modes. @key{SPC} and |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
2226 @key{TAB} behave like down-arrow, and @key{BackTab} behaves like |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
2227 up-arrow. |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
2228 |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
2229 Both @kbd{C-m} and @kbd{f} visit the file on the current |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
2230 line. @kbd{o} visits that file in another window. @kbd{q} dismisses |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
2231 the directory buffer. |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
2232 |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
2233 @kbd{x} toggles hiding of up-to-date files. |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
2234 |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
2235 @kbd{m} marks the file or directory on the current line. If the |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
2236 region is active, @kbd{m} marks all the files in the region. There |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
2237 are some restrictions when marking: a file cannot be marked if any of |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
2238 its parent directories are marked, and a directory cannot be marked if |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
2239 any files in it or in its child directories are marked. |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
2240 |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
2241 @kbd{M} marks all the files with the same VC state as the current |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
2242 file if the cursor is on a file. If the cursor is on a directory, it |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
2243 marks all child files. With a prefix argument: marks all files and |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
2244 directories. |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
2245 |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
2246 @kbd{u} unmarks the file or directory on the current line. If the |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
2247 region is active, it unmarks all the files in the region. |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
2248 |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
2249 @kbd{U} marks all the files with the same VC state as the current file |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
2250 if the cursor is on a file. If the cursor is on a directory, it |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
2251 unmarks all child files. With a prefix argument: unmarks all marked |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
2252 files and directories. |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
2253 |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
2254 It is possible to do search, search and replace, incremental search, |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
2255 and incremental regexp search on multiple files. These commands will |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
2256 work on all the marked files or the current file if nothing is marked. |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
2257 If a directory is marked, the files in that directory shown in the VC |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
2258 directory buffer will be used. |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
2259 |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
2260 @kbd{S} searches the marked files. |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
2261 |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
2262 @kbd{Q} does a query replace on the marked files. |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
2263 |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
2264 @kbd{M-s a C-s} does an incremental search on the marked files. |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
2265 |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
2266 @kbd{M-s a C-M-s} does an incremental search on the marked files. |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
2267 |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
2268 Commands are also accessible from the VC-dir menu. Note that some VC |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
2269 backends use the VC-dir menu to make available extra backend specific |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
2270 commands. |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
2271 |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
2272 Normal VC commands with the @kbd{C-x v} prefix work in VC directory |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
2273 buffers. Some single-key shortcuts are available as well; @kbd{=}, |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
2274 @kbd{+}, @kbd{l}, @kbd{i}, and @kbd{v} behave as through prefixed with |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
2275 @kbd{C-x v}. |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
2276 |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
2277 The command @kbd{C-x v v} (@code{vc-next-action}) operates on all the |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
2278 marked files, so that you can check in several files at once. |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
2279 If the underlying VC supports atomic commits of multiple-file |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
2280 changesets, @kbd{C-x v v} with a selected set of modified but not |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
2281 committed files will commit all of them at once as a single changeset. |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
2282 |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
2283 When @kbd{C-x v v} (@code{vc-next-action}) operates on a set of files, |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
2284 it requires that all of those files must be either in the same state or |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
2285 in compatible states; otherwise it will throw an error (added, |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
2286 modified and removed states are considered compatible). Note that this |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
2287 differs from the behavior of older versions of VC, which did not have |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
2288 fileset operations and simply did @code{vc-next-action} on each file |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
2289 individually. |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
2290 |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
2291 If any files are in a state that calls for commit, @kbd{C-x v v} reads a |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
2292 single log entry and uses it for the changeset as a whole. If the |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
2293 underling VCS is file- rather than changeset-oriented, the log entry |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
2294 will be replicated into the history of each file. |
84239 | 2295 |
2296 @node Branches | |
2297 @subsection Multiple Branches of a File | |
2298 @cindex branch (version control) | |
2299 @cindex trunk (version control) | |
2300 | |
2301 One use of version control is to maintain multiple ``current'' | |
85139
8ba0e30716a5
Terminology cleanup.
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85135
diff
changeset
|
2302 revisions of a file. For example, you might have different revisions of a |
84239 | 2303 program in which you are gradually adding various unfinished new |
2304 features. Each such independent line of development is called a | |
2305 @dfn{branch}. VC allows you to create branches, switch between | |
2306 different branches, and merge changes from one branch to another. | |
2307 Please note, however, that branches are not supported for SCCS. | |
2308 | |
2309 A file's main line of development is usually called the @dfn{trunk}. | |
85152
a0d3d8180a58
Revise version-control portions of the manual to include
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85139
diff
changeset
|
2310 You can create multiple branches from the trunk. How the difference |
a0d3d8180a58
Revise version-control portions of the manual to include
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85139
diff
changeset
|
2311 between trunk and branch is made visible is dependent on whether the |
a0d3d8180a58
Revise version-control portions of the manual to include
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85139
diff
changeset
|
2312 VCS uses dot-pair or monotonic version IDs. |
a0d3d8180a58
Revise version-control portions of the manual to include
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85139
diff
changeset
|
2313 |
a0d3d8180a58
Revise version-control portions of the manual to include
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85139
diff
changeset
|
2314 In VCSes with dot-pair revision IDs, the revisions on the trunk are |
a0d3d8180a58
Revise version-control portions of the manual to include
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85139
diff
changeset
|
2315 normally IDed 1.1, 1.2, 1.3, etc. At any such revision, you can |
a0d3d8180a58
Revise version-control portions of the manual to include
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85139
diff
changeset
|
2316 start an independent branch. A branch starting at revision 1.2 would |
a0d3d8180a58
Revise version-control portions of the manual to include
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85139
diff
changeset
|
2317 have revision ID 1.2.1.1, and consecutive revisions on this branch |
a0d3d8180a58
Revise version-control portions of the manual to include
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85139
diff
changeset
|
2318 would have IDs 1.2.1.2, 1.2.1.3, 1.2.1.4, and so on. If there is |
a0d3d8180a58
Revise version-control portions of the manual to include
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85139
diff
changeset
|
2319 a second branch also starting at revision 1.2, it would consist of |
a0d3d8180a58
Revise version-control portions of the manual to include
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85139
diff
changeset
|
2320 revisions 1.2.2.1, 1.2.2.2, 1.2.2.3, etc. |
a0d3d8180a58
Revise version-control portions of the manual to include
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85139
diff
changeset
|
2321 |
a0d3d8180a58
Revise version-control portions of the manual to include
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85139
diff
changeset
|
2322 In VCSes with monotonic revision IDs, trunk revisions are IDed as |
a0d3d8180a58
Revise version-control portions of the manual to include
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85139
diff
changeset
|
2323 1, 2, 3, etc. A branch from (say) revision 2 might start with 2.1 and |
a0d3d8180a58
Revise version-control portions of the manual to include
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85139
diff
changeset
|
2324 continue through 2.2, 2.3, etc. But naming conventions for branches |
a0d3d8180a58
Revise version-control portions of the manual to include
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85139
diff
changeset
|
2325 and subbranches vary widely on these systems, and some (like |
a0d3d8180a58
Revise version-control portions of the manual to include
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85139
diff
changeset
|
2326 Mercurial) never depart from the monotonic integer sequence at all. |
a0d3d8180a58
Revise version-control portions of the manual to include
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85139
diff
changeset
|
2327 Consult the documentation of the VCS you are using. |
85139
8ba0e30716a5
Terminology cleanup.
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85135
diff
changeset
|
2328 |
8ba0e30716a5
Terminology cleanup.
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85135
diff
changeset
|
2329 @cindex head revision |
85152
a0d3d8180a58
Revise version-control portions of the manual to include
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85139
diff
changeset
|
2330 If you omit the final component of a dot-pair revision ID, that is called a |
a0d3d8180a58
Revise version-control portions of the manual to include
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85139
diff
changeset
|
2331 @dfn{branch ID}. It refers to the highest existing revision on that |
85139
8ba0e30716a5
Terminology cleanup.
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85135
diff
changeset
|
2332 branch---the @dfn{head revision} of that branch. The branches in the |
85152
a0d3d8180a58
Revise version-control portions of the manual to include
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85139
diff
changeset
|
2333 dot-pair example above have branch IDs 1.2.1 and 1.2.2. |
84239 | 2334 |
2335 @menu | |
2336 * Switching Branches:: How to get to another existing branch. | |
2337 * Creating Branches:: How to start a new branch. | |
2338 * Merging:: Transferring changes between branches. | |
2339 * Multi-User Branching:: Multiple users working at multiple branches | |
2340 in parallel. | |
2341 @end menu | |
2342 | |
2343 @node Switching Branches | |
2344 @subsubsection Switching between Branches | |
2345 | |
2346 To switch between branches, type @kbd{C-u C-x v v} and specify the | |
85139
8ba0e30716a5
Terminology cleanup.
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85135
diff
changeset
|
2347 revision ID you want to select. On a locking-based system, this |
85063
4cdaedc4a269
More manual updates and additions bringing it current with modern
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85061
diff
changeset
|
2348 version is then visited @emph{unlocked} (write-protected), so you can |
4cdaedc4a269
More manual updates and additions bringing it current with modern
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85061
diff
changeset
|
2349 examine it before locking it. Switching branches in this way is allowed |
4cdaedc4a269
More manual updates and additions bringing it current with modern
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85061
diff
changeset
|
2350 only when the file is not locked. |
84239 | 2351 |
85152
a0d3d8180a58
Revise version-control portions of the manual to include
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85139
diff
changeset
|
2352 On a VCS with dot-pair IDs, you can omit the minor part, thus giving |
a0d3d8180a58
Revise version-control portions of the manual to include
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85139
diff
changeset
|
2353 only the branch ID; this takes you to the head version on the |
a0d3d8180a58
Revise version-control portions of the manual to include
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85139
diff
changeset
|
2354 chosen branch. If you only type @key{RET}, Emacs goes to the highest |
a0d3d8180a58
Revise version-control portions of the manual to include
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85139
diff
changeset
|
2355 version on the trunk. |
84239 | 2356 |
2357 After you have switched to any branch (including the main branch), you | |
2358 stay on it for subsequent VC commands, until you explicitly select some | |
2359 other branch. | |
2360 | |
2361 @node Creating Branches | |
2362 @subsubsection Creating New Branches | |
2363 | |
85139
8ba0e30716a5
Terminology cleanup.
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85135
diff
changeset
|
2364 To create a new branch from a head revision (one that is the latest in |
8ba0e30716a5
Terminology cleanup.
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85135
diff
changeset
|
2365 the branch that contains it), first select that revision if necessary, |
84239 | 2366 lock it with @kbd{C-x v v}, and make whatever changes you want. Then, |
2367 when you check in the changes, use @kbd{C-u C-x v v}. This lets you | |
85152
a0d3d8180a58
Revise version-control portions of the manual to include
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85139
diff
changeset
|
2368 specify the revision ID for the new revision. You should specify a |
a0d3d8180a58
Revise version-control portions of the manual to include
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85139
diff
changeset
|
2369 suitable branch ID for a branch starting at the current revision. |
a0d3d8180a58
Revise version-control portions of the manual to include
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85139
diff
changeset
|
2370 For example, if the current revision is 2.5, the branch ID should be |
84239 | 2371 2.5.1, 2.5.2, and so on, depending on the number of existing branches at |
2372 that point. | |
2373 | |
85139
8ba0e30716a5
Terminology cleanup.
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85135
diff
changeset
|
2374 To create a new branch at an older revision (one that is no longer the |
8ba0e30716a5
Terminology cleanup.
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85135
diff
changeset
|
2375 head of a branch), first select that revision (@pxref{Switching |
85063
4cdaedc4a269
More manual updates and additions bringing it current with modern
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85061
diff
changeset
|
2376 Branches}). Your procedure will then differ depending on whether you |
4cdaedc4a269
More manual updates and additions bringing it current with modern
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85061
diff
changeset
|
2377 are using a locking or merging-based VCS. |
4cdaedc4a269
More manual updates and additions bringing it current with modern
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85061
diff
changeset
|
2378 |
85139
8ba0e30716a5
Terminology cleanup.
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85135
diff
changeset
|
2379 On a locking VCS, you will need to lock the old revision branch with |
85063
4cdaedc4a269
More manual updates and additions bringing it current with modern
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85061
diff
changeset
|
2380 @kbd{C-x v v}. You'll be asked to confirm, when you lock the old |
85139
8ba0e30716a5
Terminology cleanup.
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85135
diff
changeset
|
2381 revision, that you really mean to create a new branch---if you say no, |
8ba0e30716a5
Terminology cleanup.
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85135
diff
changeset
|
2382 you'll be offered a chance to lock the latest revision instead. On |
85063
4cdaedc4a269
More manual updates and additions bringing it current with modern
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85061
diff
changeset
|
2383 a merging-based VCS you will skip this step. |
84239 | 2384 |
2385 Then make your changes and type @kbd{C-x v v} again to check in a new | |
85139
8ba0e30716a5
Terminology cleanup.
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85135
diff
changeset
|
2386 revision. This automatically creates a new branch starting from the |
8ba0e30716a5
Terminology cleanup.
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85135
diff
changeset
|
2387 selected revision. You need not specially request a new branch, because |
8ba0e30716a5
Terminology cleanup.
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85135
diff
changeset
|
2388 that's the only way to add a new revision at a point that is not the head |
84239 | 2389 of a branch. |
2390 | |
2391 After the branch is created, you ``stay'' on it. That means that | |
85139
8ba0e30716a5
Terminology cleanup.
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85135
diff
changeset
|
2392 subsequent check-ins create new revisions on that branch. To leave the |
8ba0e30716a5
Terminology cleanup.
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85135
diff
changeset
|
2393 branch, you must explicitly select a different revision with @kbd{C-u C-x |
84239 | 2394 v v}. To transfer changes from one branch to another, use the merge |
2395 command, described in the next section. | |
2396 | |
2397 @node Merging | |
2398 @subsubsection Merging Branches | |
2399 | |
2400 @cindex merging changes | |
2401 When you have finished the changes on a certain branch, you will | |
2402 often want to incorporate them into the file's main line of development | |
2403 (the trunk). This is not a trivial operation, because development might | |
2404 also have proceeded on the trunk, so that you must @dfn{merge} the | |
2405 changes into a file that has already been changed otherwise. VC allows | |
2406 you to do this (and other things) with the @code{vc-merge} command. | |
2407 | |
2408 @table @kbd | |
2409 @item C-x v m (vc-merge) | |
2410 Merge changes into the work file. | |
2411 @end table | |
2412 | |
2413 @kindex C-x v m | |
2414 @findex vc-merge | |
2415 @kbd{C-x v m} (@code{vc-merge}) takes a set of changes and merges it | |
2416 into the current version of the work file. It firsts asks you in the | |
2417 minibuffer where the changes should come from. If you just type | |
2418 @key{RET}, Emacs merges any changes that were made on the same branch | |
2419 since you checked the file out (we call this @dfn{merging the news}). | |
2420 This is the common way to pick up recent changes from the repository, | |
2421 regardless of whether you have already changed the file yourself. | |
2422 | |
85152
a0d3d8180a58
Revise version-control portions of the manual to include
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85139
diff
changeset
|
2423 You can also enter a branch ID or a pair of revision IDs in |
84239 | 2424 the minibuffer. Then @kbd{C-x v m} finds the changes from that |
85139
8ba0e30716a5
Terminology cleanup.
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85135
diff
changeset
|
2425 branch, or the differences between the two revisions you specified, and |
8ba0e30716a5
Terminology cleanup.
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85135
diff
changeset
|
2426 merges them into the current revision of the current file. |
84239 | 2427 |
2428 As an example, suppose that you have finished a certain feature on | |
2429 branch 1.3.1. In the meantime, development on the trunk has proceeded | |
85139
8ba0e30716a5
Terminology cleanup.
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85135
diff
changeset
|
2430 to revision 1.5. To merge the changes from the branch to the trunk, |
8ba0e30716a5
Terminology cleanup.
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85135
diff
changeset
|
2431 first go to the head revision of the trunk, by typing @kbd{C-u C-x v v |
8ba0e30716a5
Terminology cleanup.
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85135
diff
changeset
|
2432 @key{RET}}. Revision 1.5 is now current. If locking is used for the file, |
8ba0e30716a5
Terminology cleanup.
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85135
diff
changeset
|
2433 type @kbd{C-x v v} to lock revision 1.5 so that you can change it. Next, |
84239 | 2434 type @kbd{C-x v m 1.3.1 @key{RET}}. This takes the entire set of changes on |
85139
8ba0e30716a5
Terminology cleanup.
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85135
diff
changeset
|
2435 branch 1.3.1 (relative to revision 1.3, where the branch started, up to |
8ba0e30716a5
Terminology cleanup.
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85135
diff
changeset
|
2436 the last revision on the branch) and merges it into the current revision |
84239 | 2437 of the work file. You can now check in the changed file, thus creating |
85139
8ba0e30716a5
Terminology cleanup.
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85135
diff
changeset
|
2438 revision 1.6 containing the changes from the branch. |
84239 | 2439 |
2440 It is possible to do further editing after merging the branch, before | |
2441 the next check-in. But it is usually wiser to check in the merged | |
85139
8ba0e30716a5
Terminology cleanup.
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85135
diff
changeset
|
2442 revision, then lock it and make the further changes. This will keep |
84239 | 2443 a better record of the history of changes. |
2444 | |
2445 @cindex conflicts | |
2446 @cindex resolving conflicts | |
2447 When you merge changes into a file that has itself been modified, the | |
2448 changes might overlap. We call this situation a @dfn{conflict}, and | |
2449 reconciling the conflicting changes is called @dfn{resolving a | |
2450 conflict}. | |
2451 | |
2452 Whenever conflicts occur during merging, VC detects them, tells you | |
2453 about them in the echo area, and asks whether you want help in merging. | |
2454 If you say yes, it starts an Ediff session (@pxref{Top, | |
2455 Ediff, Ediff, ediff, The Ediff Manual}). | |
2456 | |
2457 If you say no, the conflicting changes are both inserted into the | |
2458 file, surrounded by @dfn{conflict markers}. The example below shows how | |
2459 a conflict region looks; the file is called @samp{name} and the current | |
85139
8ba0e30716a5
Terminology cleanup.
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85135
diff
changeset
|
2460 master file revision with user B's changes in it is 1.11. |
84239 | 2461 |
2462 @c @w here is so CVS won't think this is a conflict. | |
2463 @smallexample | |
2464 @group | |
2465 @w{<}<<<<<< name | |
2466 @var{User A's version} | |
2467 ======= | |
2468 @var{User B's version} | |
2469 @w{>}>>>>>> 1.11 | |
2470 @end group | |
2471 @end smallexample | |
2472 | |
2473 @cindex vc-resolve-conflicts | |
2474 Then you can resolve the conflicts by editing the file manually. Or | |
2475 you can type @code{M-x vc-resolve-conflicts} after visiting the file. | |
2476 This starts an Ediff session, as described above. Don't forget to | |
2477 check in the merged version afterwards. | |
2478 | |
2479 @node Multi-User Branching | |
2480 @subsubsection Multi-User Branching | |
2481 | |
2482 It is often useful for multiple developers to work simultaneously on | |
85152
a0d3d8180a58
Revise version-control portions of the manual to include
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85139
diff
changeset
|
2483 different branches of a file. CVS and later systems allow this by |
a0d3d8180a58
Revise version-control portions of the manual to include
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85139
diff
changeset
|
2484 default; for RCS, it is possible if you create multiple source |
a0d3d8180a58
Revise version-control portions of the manual to include
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85139
diff
changeset
|
2485 directories. Each source directory should have a link named |
a0d3d8180a58
Revise version-control portions of the manual to include
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85139
diff
changeset
|
2486 @file{RCS} which points to a common directory of RCS master files. |
a0d3d8180a58
Revise version-control portions of the manual to include
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85139
diff
changeset
|
2487 Then each source directory can have its own choice of selected |
a0d3d8180a58
Revise version-control portions of the manual to include
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85139
diff
changeset
|
2488 revisions, but all share the same common RCS records. |
84239 | 2489 |
2490 This technique works reliably and automatically, provided that the | |
2491 source files contain RCS version headers | |
2492 @iftex | |
2493 (@pxref{Version Headers,,,emacs-xtra, Specialized Emacs Features}). | |
2494 @end iftex | |
2495 @ifnottex | |
2496 (@pxref{Version Headers}). | |
2497 @end ifnottex | |
85152
a0d3d8180a58
Revise version-control portions of the manual to include
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85139
diff
changeset
|
2498 The headers enable Emacs to be sure, at all times, which revision |
a0d3d8180a58
Revise version-control portions of the manual to include
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85139
diff
changeset
|
2499 ID is present in the work file. |
84239 | 2500 |
2501 If the files do not have version headers, you must instead tell Emacs | |
2502 explicitly in each session which branch you are working on. To do this, | |
2503 first find the file, then type @kbd{C-u C-x v v} and specify the correct | |
85152
a0d3d8180a58
Revise version-control portions of the manual to include
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85139
diff
changeset
|
2504 branch ID. This ensures that Emacs knows which branch it is using |
84239 | 2505 during this particular editing session. |
2506 | |
2507 @ifnottex | |
99002
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
2508 @include vc1-xtra.texi |
84239 | 2509 @end ifnottex |
2510 | |
2511 @node Directories | |
2512 @section File Directories | |
2513 | |
2514 @cindex file directory | |
2515 @cindex directory listing | |
2516 The file system groups files into @dfn{directories}. A @dfn{directory | |
2517 listing} is a list of all the files in a directory. Emacs provides | |
2518 commands to create and delete directories, and to make directory | |
2519 listings in brief format (file names only) and verbose format (sizes, | |
2520 dates, and authors included). Emacs also includes a directory browser | |
2521 feature called Dired; see @ref{Dired}. | |
2522 | |
2523 @table @kbd | |
2524 @item C-x C-d @var{dir-or-pattern} @key{RET} | |
2525 Display a brief directory listing (@code{list-directory}). | |
2526 @item C-u C-x C-d @var{dir-or-pattern} @key{RET} | |
2527 Display a verbose directory listing. | |
2528 @item M-x make-directory @key{RET} @var{dirname} @key{RET} | |
2529 Create a new directory named @var{dirname}. | |
2530 @item M-x delete-directory @key{RET} @var{dirname} @key{RET} | |
2531 Delete the directory named @var{dirname}. It must be empty, | |
2532 or you get an error. | |
2533 @end table | |
2534 | |
2535 @findex list-directory | |
2536 @kindex C-x C-d | |
2537 The command to display a directory listing is @kbd{C-x C-d} | |
2538 (@code{list-directory}). It reads using the minibuffer a file name | |
2539 which is either a directory to be listed or a wildcard-containing | |
2540 pattern for the files to be listed. For example, | |
2541 | |
2542 @example | |
2543 C-x C-d /u2/emacs/etc @key{RET} | |
2544 @end example | |
2545 | |
2546 @noindent | |
2547 lists all the files in directory @file{/u2/emacs/etc}. Here is an | |
2548 example of specifying a file name pattern: | |
2549 | |
2550 @example | |
2551 C-x C-d /u2/emacs/src/*.c @key{RET} | |
2552 @end example | |
2553 | |
2554 Normally, @kbd{C-x C-d} displays a brief directory listing containing | |
2555 just file names. A numeric argument (regardless of value) tells it to | |
2556 make a verbose listing including sizes, dates, and owners (like | |
2557 @samp{ls -l}). | |
2558 | |
2559 @vindex list-directory-brief-switches | |
2560 @vindex list-directory-verbose-switches | |
2561 The text of a directory listing is mostly obtained by running | |
2562 @code{ls} in an inferior process. Two Emacs variables control the | |
2563 switches passed to @code{ls}: @code{list-directory-brief-switches} is | |
2564 a string giving the switches to use in brief listings (@code{"-CF"} by | |
2565 default), and @code{list-directory-verbose-switches} is a string | |
2566 giving the switches to use in a verbose listing (@code{"-l"} by | |
2567 default). | |
2568 | |
2569 @vindex directory-free-space-program | |
2570 @vindex directory-free-space-args | |
2571 In verbose directory listings, Emacs adds information about the | |
2572 amount of free space on the disk that contains the directory. To do | |
2573 this, it runs the program specified by | |
2574 @code{directory-free-space-program} with arguments | |
2575 @code{directory-free-space-args}. | |
2576 | |
2577 @node Comparing Files | |
2578 @section Comparing Files | |
2579 @cindex comparing files | |
2580 | |
2581 @findex diff | |
2582 @vindex diff-switches | |
99011
5d3f807c7d3e
(Comparing Files): Note that diff uses the minibuffer, and
Chong Yidong <cyd@stupidchicken.com>
parents:
99002
diff
changeset
|
2583 The command @kbd{M-x diff} prompts for two file names, using the |
5d3f807c7d3e
(Comparing Files): Note that diff uses the minibuffer, and
Chong Yidong <cyd@stupidchicken.com>
parents:
99002
diff
changeset
|
2584 minibuffer, and displays the differences between the two files in a |
5d3f807c7d3e
(Comparing Files): Note that diff uses the minibuffer, and
Chong Yidong <cyd@stupidchicken.com>
parents:
99002
diff
changeset
|
2585 buffer named @samp{*diff*}. This works by running the @command{diff} |
5d3f807c7d3e
(Comparing Files): Note that diff uses the minibuffer, and
Chong Yidong <cyd@stupidchicken.com>
parents:
99002
diff
changeset
|
2586 program, using options taken from the variable @code{diff-switches}. |
5d3f807c7d3e
(Comparing Files): Note that diff uses the minibuffer, and
Chong Yidong <cyd@stupidchicken.com>
parents:
99002
diff
changeset
|
2587 The value of @code{diff-switches} should be a string; the default is |
5d3f807c7d3e
(Comparing Files): Note that diff uses the minibuffer, and
Chong Yidong <cyd@stupidchicken.com>
parents:
99002
diff
changeset
|
2588 @code{"-c"} to specify a context diff. @xref{Top,, Diff, diff, |
5d3f807c7d3e
(Comparing Files): Note that diff uses the minibuffer, and
Chong Yidong <cyd@stupidchicken.com>
parents:
99002
diff
changeset
|
2589 Comparing and Merging Files}, for more information about |
5d3f807c7d3e
(Comparing Files): Note that diff uses the minibuffer, and
Chong Yidong <cyd@stupidchicken.com>
parents:
99002
diff
changeset
|
2590 @command{diff} output formats. |
5d3f807c7d3e
(Comparing Files): Note that diff uses the minibuffer, and
Chong Yidong <cyd@stupidchicken.com>
parents:
99002
diff
changeset
|
2591 |
5d3f807c7d3e
(Comparing Files): Note that diff uses the minibuffer, and
Chong Yidong <cyd@stupidchicken.com>
parents:
99002
diff
changeset
|
2592 The output of the @code{diff} command is shown using a major mode |
5d3f807c7d3e
(Comparing Files): Note that diff uses the minibuffer, and
Chong Yidong <cyd@stupidchicken.com>
parents:
99002
diff
changeset
|
2593 called Diff mode. @xref{Diff Mode}. |
84239 | 2594 |
2595 @findex diff-backup | |
99011
5d3f807c7d3e
(Comparing Files): Note that diff uses the minibuffer, and
Chong Yidong <cyd@stupidchicken.com>
parents:
99002
diff
changeset
|
2596 The command @kbd{M-x diff-backup} compares a specified file with its |
5d3f807c7d3e
(Comparing Files): Note that diff uses the minibuffer, and
Chong Yidong <cyd@stupidchicken.com>
parents:
99002
diff
changeset
|
2597 most recent backup. If you specify the name of a backup file, |
5d3f807c7d3e
(Comparing Files): Note that diff uses the minibuffer, and
Chong Yidong <cyd@stupidchicken.com>
parents:
99002
diff
changeset
|
2598 @code{diff-backup} compares it with the source file that it is a |
5d3f807c7d3e
(Comparing Files): Note that diff uses the minibuffer, and
Chong Yidong <cyd@stupidchicken.com>
parents:
99002
diff
changeset
|
2599 backup of. In all other respects, this behaves like @kbd{M-x diff}. |
84239 | 2600 |
2601 @findex compare-windows | |
2602 The command @kbd{M-x compare-windows} compares the text in the | |
2603 current window with that in the next window. (For more information | |
2604 about windows in Emacs, @ref{Windows}.) Comparison starts at point in | |
2605 each window, after pushing each initial point value on the mark ring | |
2606 in its respective buffer. Then it moves point forward in each window, | |
2607 one character at a time, until it reaches characters that don't match. | |
2608 Then the command exits. | |
2609 | |
2610 If point in the two windows is followed by non-matching text when | |
2611 the command starts, @kbd{M-x compare-windows} tries heuristically to | |
2612 advance up to matching text in the two windows, and then exits. So if | |
2613 you use @kbd{M-x compare-windows} repeatedly, each time it either | |
2614 skips one matching range or finds the start of another. | |
2615 | |
2616 @vindex compare-ignore-case | |
2617 @vindex compare-ignore-whitespace | |
2618 With a numeric argument, @code{compare-windows} ignores changes in | |
2619 whitespace. If the variable @code{compare-ignore-case} is | |
2620 non-@code{nil}, the comparison ignores differences in case as well. | |
2621 If the variable @code{compare-ignore-whitespace} is non-@code{nil}, | |
2622 @code{compare-windows} normally ignores changes in whitespace, and a | |
2623 prefix argument turns that off. | |
2624 | |
2625 @cindex Smerge mode | |
2626 @findex smerge-mode | |
2627 @cindex failed merges | |
2628 @cindex merges, failed | |
2629 @cindex comparing 3 files (@code{diff3}) | |
2630 You can use @kbd{M-x smerge-mode} to turn on Smerge mode, a minor | |
2631 mode for editing output from the @command{diff3} program. This is | |
2632 typically the result of a failed merge from a version control system | |
2633 ``update'' outside VC, due to conflicting changes to a file. Smerge | |
2634 mode provides commands to resolve conflicts by selecting specific | |
2635 changes. | |
2636 | |
2637 @iftex | |
2638 @xref{Emerge,,, emacs-xtra, Specialized Emacs Features}, | |
2639 @end iftex | |
2640 @ifnottex | |
2641 @xref{Emerge}, | |
2642 @end ifnottex | |
2643 for the Emerge facility, which provides a powerful interface for | |
2644 merging files. | |
2645 | |
2646 @node Diff Mode | |
2647 @section Diff Mode | |
2648 @cindex Diff mode | |
2649 @findex diff-mode | |
2650 @cindex patches, editing | |
2651 | |
99011
5d3f807c7d3e
(Comparing Files): Note that diff uses the minibuffer, and
Chong Yidong <cyd@stupidchicken.com>
parents:
99002
diff
changeset
|
2652 Diff mode is a major mode used for the output of @kbd{M-x diff} and |
5d3f807c7d3e
(Comparing Files): Note that diff uses the minibuffer, and
Chong Yidong <cyd@stupidchicken.com>
parents:
99002
diff
changeset
|
2653 other similar commands, as well as the output of the @command{diff} |
5d3f807c7d3e
(Comparing Files): Note that diff uses the minibuffer, and
Chong Yidong <cyd@stupidchicken.com>
parents:
99002
diff
changeset
|
2654 program. This kind of output is called a @dfn{patch}, because it can |
5d3f807c7d3e
(Comparing Files): Note that diff uses the minibuffer, and
Chong Yidong <cyd@stupidchicken.com>
parents:
99002
diff
changeset
|
2655 be passed to the @command{patch} command to automatically apply the |
5d3f807c7d3e
(Comparing Files): Note that diff uses the minibuffer, and
Chong Yidong <cyd@stupidchicken.com>
parents:
99002
diff
changeset
|
2656 specified changes. To select Diff mode manually, type @kbd{M-x |
84239 | 2657 diff-mode}. |
2658 | |
99011
5d3f807c7d3e
(Comparing Files): Note that diff uses the minibuffer, and
Chong Yidong <cyd@stupidchicken.com>
parents:
99002
diff
changeset
|
2659 @cindex hunk, diff |
5d3f807c7d3e
(Comparing Files): Note that diff uses the minibuffer, and
Chong Yidong <cyd@stupidchicken.com>
parents:
99002
diff
changeset
|
2660 The changes specified in a patch are grouped into @dfn{hunks}, which |
5d3f807c7d3e
(Comparing Files): Note that diff uses the minibuffer, and
Chong Yidong <cyd@stupidchicken.com>
parents:
99002
diff
changeset
|
2661 are contiguous chunks of text that contain one or more changed lines. |
5d3f807c7d3e
(Comparing Files): Note that diff uses the minibuffer, and
Chong Yidong <cyd@stupidchicken.com>
parents:
99002
diff
changeset
|
2662 Hunks can also include unchanged lines to provide context for the |
5d3f807c7d3e
(Comparing Files): Note that diff uses the minibuffer, and
Chong Yidong <cyd@stupidchicken.com>
parents:
99002
diff
changeset
|
2663 changes. Each hunk is preceded by a @dfn{hunk header}, which |
5d3f807c7d3e
(Comparing Files): Note that diff uses the minibuffer, and
Chong Yidong <cyd@stupidchicken.com>
parents:
99002
diff
changeset
|
2664 specifies the old and new line numbers at which the hunk occurs. Diff |
5d3f807c7d3e
(Comparing Files): Note that diff uses the minibuffer, and
Chong Yidong <cyd@stupidchicken.com>
parents:
99002
diff
changeset
|
2665 mode highlights each hunk header, to distinguish it from the actual |
5d3f807c7d3e
(Comparing Files): Note that diff uses the minibuffer, and
Chong Yidong <cyd@stupidchicken.com>
parents:
99002
diff
changeset
|
2666 contents of the hunk. |
5d3f807c7d3e
(Comparing Files): Note that diff uses the minibuffer, and
Chong Yidong <cyd@stupidchicken.com>
parents:
99002
diff
changeset
|
2667 |
5d3f807c7d3e
(Comparing Files): Note that diff uses the minibuffer, and
Chong Yidong <cyd@stupidchicken.com>
parents:
99002
diff
changeset
|
2668 @vindex diff-update-on-the-fly |
5d3f807c7d3e
(Comparing Files): Note that diff uses the minibuffer, and
Chong Yidong <cyd@stupidchicken.com>
parents:
99002
diff
changeset
|
2669 You can edit a Diff mode buffer like any other buffer. (If it is |
5d3f807c7d3e
(Comparing Files): Note that diff uses the minibuffer, and
Chong Yidong <cyd@stupidchicken.com>
parents:
99002
diff
changeset
|
2670 read-only, you need to make it writable first. @xref{Misc Buffer}.) |
5d3f807c7d3e
(Comparing Files): Note that diff uses the minibuffer, and
Chong Yidong <cyd@stupidchicken.com>
parents:
99002
diff
changeset
|
2671 Whenever you change a hunk, Diff mode attempts to automatically |
5d3f807c7d3e
(Comparing Files): Note that diff uses the minibuffer, and
Chong Yidong <cyd@stupidchicken.com>
parents:
99002
diff
changeset
|
2672 correct the line numbers in the hunk headers, to ensure that the diff |
5d3f807c7d3e
(Comparing Files): Note that diff uses the minibuffer, and
Chong Yidong <cyd@stupidchicken.com>
parents:
99002
diff
changeset
|
2673 remains ``correct''. To disable automatic line number correction, |
5d3f807c7d3e
(Comparing Files): Note that diff uses the minibuffer, and
Chong Yidong <cyd@stupidchicken.com>
parents:
99002
diff
changeset
|
2674 change the variable @code{diff-update-on-the-fly} to @code{nil}. |
5d3f807c7d3e
(Comparing Files): Note that diff uses the minibuffer, and
Chong Yidong <cyd@stupidchicken.com>
parents:
99002
diff
changeset
|
2675 |
5d3f807c7d3e
(Comparing Files): Note that diff uses the minibuffer, and
Chong Yidong <cyd@stupidchicken.com>
parents:
99002
diff
changeset
|
2676 Diff mode treats each hunk as an ``error message,'' similar to |
5d3f807c7d3e
(Comparing Files): Note that diff uses the minibuffer, and
Chong Yidong <cyd@stupidchicken.com>
parents:
99002
diff
changeset
|
2677 Compilation mode. Thus, you can use commands such as @kbd{C-x '} to |
5d3f807c7d3e
(Comparing Files): Note that diff uses the minibuffer, and
Chong Yidong <cyd@stupidchicken.com>
parents:
99002
diff
changeset
|
2678 visit the corresponding source locations. @xref{Compilation Mode}. |
5d3f807c7d3e
(Comparing Files): Note that diff uses the minibuffer, and
Chong Yidong <cyd@stupidchicken.com>
parents:
99002
diff
changeset
|
2679 |
5d3f807c7d3e
(Comparing Files): Note that diff uses the minibuffer, and
Chong Yidong <cyd@stupidchicken.com>
parents:
99002
diff
changeset
|
2680 In addition, Diff mode provides the following commands to navigate, |
84239 | 2681 manipulate and apply parts of patches: |
2682 | |
2683 @table @kbd | |
2684 @item M-n | |
97355
18156178166e
(Log Buffer, Diff Mode): Fix last changes. Add indexing.
Eli Zaretskii <eliz@gnu.org>
parents:
97349
diff
changeset
|
2685 @findex diff-hunk-next |
84239 | 2686 Move to the next hunk-start (@code{diff-hunk-next}). |
2687 | |
2688 @item M-p | |
97355
18156178166e
(Log Buffer, Diff Mode): Fix last changes. Add indexing.
Eli Zaretskii <eliz@gnu.org>
parents:
97349
diff
changeset
|
2689 @findex diff-hunk-prev |
84239 | 2690 Move to the previous hunk-start (@code{diff-hunk-prev}). |
2691 | |
2692 @item M-@} | |
97355
18156178166e
(Log Buffer, Diff Mode): Fix last changes. Add indexing.
Eli Zaretskii <eliz@gnu.org>
parents:
97349
diff
changeset
|
2693 @findex diff-file-next |
84239 | 2694 Move to the next file-start, in a multi-file patch |
2695 (@code{diff-file-next}). | |
2696 | |
2697 @item M-@{ | |
97355
18156178166e
(Log Buffer, Diff Mode): Fix last changes. Add indexing.
Eli Zaretskii <eliz@gnu.org>
parents:
97349
diff
changeset
|
2698 @findex diff-file-prev |
84239 | 2699 Move to the previous file-start, in a multi-file patch |
2700 (@code{diff-file-prev}). | |
2701 | |
2702 @item M-k | |
97355
18156178166e
(Log Buffer, Diff Mode): Fix last changes. Add indexing.
Eli Zaretskii <eliz@gnu.org>
parents:
97349
diff
changeset
|
2703 @findex diff-hunk-kill |
84239 | 2704 Kill the hunk at point (@code{diff-hunk-kill}). |
2705 | |
2706 @item M-K | |
97355
18156178166e
(Log Buffer, Diff Mode): Fix last changes. Add indexing.
Eli Zaretskii <eliz@gnu.org>
parents:
97349
diff
changeset
|
2707 @findex diff-file-kill |
84239 | 2708 In a multi-file patch, kill the current file part. |
2709 (@code{diff-file-kill}). | |
2710 | |
2711 @item C-c C-a | |
97355
18156178166e
(Log Buffer, Diff Mode): Fix last changes. Add indexing.
Eli Zaretskii <eliz@gnu.org>
parents:
97349
diff
changeset
|
2712 @findex diff-apply-hunk |
84239 | 2713 Apply this hunk to its target file (@code{diff-apply-hunk}). With a |
2714 prefix argument of @kbd{C-u}, revert this hunk. | |
2715 | |
99011
5d3f807c7d3e
(Comparing Files): Note that diff uses the minibuffer, and
Chong Yidong <cyd@stupidchicken.com>
parents:
99002
diff
changeset
|
2716 @item C-c C-b |
5d3f807c7d3e
(Comparing Files): Note that diff uses the minibuffer, and
Chong Yidong <cyd@stupidchicken.com>
parents:
99002
diff
changeset
|
2717 @findex diff-refine-hunk |
5d3f807c7d3e
(Comparing Files): Note that diff uses the minibuffer, and
Chong Yidong <cyd@stupidchicken.com>
parents:
99002
diff
changeset
|
2718 Highlight the changes of the hunk at point with a finer granularity |
5d3f807c7d3e
(Comparing Files): Note that diff uses the minibuffer, and
Chong Yidong <cyd@stupidchicken.com>
parents:
99002
diff
changeset
|
2719 (@code{diff-refine-hunk}). This allows you to see exactly which parts |
5d3f807c7d3e
(Comparing Files): Note that diff uses the minibuffer, and
Chong Yidong <cyd@stupidchicken.com>
parents:
99002
diff
changeset
|
2720 of each changed line were actually changed. |
5d3f807c7d3e
(Comparing Files): Note that diff uses the minibuffer, and
Chong Yidong <cyd@stupidchicken.com>
parents:
99002
diff
changeset
|
2721 |
84239 | 2722 @item C-c C-c |
97355
18156178166e
(Log Buffer, Diff Mode): Fix last changes. Add indexing.
Eli Zaretskii <eliz@gnu.org>
parents:
97349
diff
changeset
|
2723 @findex diff-goto-source |
18156178166e
(Log Buffer, Diff Mode): Fix last changes. Add indexing.
Eli Zaretskii <eliz@gnu.org>
parents:
97349
diff
changeset
|
2724 Go to the source file and line corresponding to this hunk |
18156178166e
(Log Buffer, Diff Mode): Fix last changes. Add indexing.
Eli Zaretskii <eliz@gnu.org>
parents:
97349
diff
changeset
|
2725 (@code{diff-goto-source}). |
84239 | 2726 |
2727 @item C-c C-e | |
97355
18156178166e
(Log Buffer, Diff Mode): Fix last changes. Add indexing.
Eli Zaretskii <eliz@gnu.org>
parents:
97349
diff
changeset
|
2728 @findex diff-ediff-patch |
84239 | 2729 Start an Ediff session with the patch (@code{diff-ediff-patch}). |
2730 @xref{Top, Ediff, Ediff, ediff, The Ediff Manual}. | |
2731 | |
2732 @item C-c C-n | |
97355
18156178166e
(Log Buffer, Diff Mode): Fix last changes. Add indexing.
Eli Zaretskii <eliz@gnu.org>
parents:
97349
diff
changeset
|
2733 @findex diff-restrict-view |
84239 | 2734 Restrict the view to the current hunk (@code{diff-restrict-view}). |
2735 @xref{Narrowing}. With a prefix argument of @kbd{C-u}, restrict the | |
97355
18156178166e
(Log Buffer, Diff Mode): Fix last changes. Add indexing.
Eli Zaretskii <eliz@gnu.org>
parents:
97349
diff
changeset
|
2736 view to the current file of a multiple-file patch. To widen again, |
18156178166e
(Log Buffer, Diff Mode): Fix last changes. Add indexing.
Eli Zaretskii <eliz@gnu.org>
parents:
97349
diff
changeset
|
2737 use @kbd{C-x n w} (@code{widen}). |
84239 | 2738 |
2739 @item C-c C-r | |
97355
18156178166e
(Log Buffer, Diff Mode): Fix last changes. Add indexing.
Eli Zaretskii <eliz@gnu.org>
parents:
97349
diff
changeset
|
2740 @findex diff-reverse-direction |
84239 | 2741 Reverse the direction of comparison for the entire buffer |
2742 (@code{diff-reverse-direction}). | |
2743 | |
2744 @item C-c C-s | |
97355
18156178166e
(Log Buffer, Diff Mode): Fix last changes. Add indexing.
Eli Zaretskii <eliz@gnu.org>
parents:
97349
diff
changeset
|
2745 @findex diff-split-hunk |
84239 | 2746 Split the hunk at point (@code{diff-split-hunk}). This is for |
97355
18156178166e
(Log Buffer, Diff Mode): Fix last changes. Add indexing.
Eli Zaretskii <eliz@gnu.org>
parents:
97349
diff
changeset
|
2747 manually editing patches, and only works with the @dfn{unified diff |
18156178166e
(Log Buffer, Diff Mode): Fix last changes. Add indexing.
Eli Zaretskii <eliz@gnu.org>
parents:
97349
diff
changeset
|
2748 format} produced by the @option{-u} or @option{--unified} options to |
18156178166e
(Log Buffer, Diff Mode): Fix last changes. Add indexing.
Eli Zaretskii <eliz@gnu.org>
parents:
97349
diff
changeset
|
2749 the @command{diff} program. If you need to split a hunk in the |
18156178166e
(Log Buffer, Diff Mode): Fix last changes. Add indexing.
Eli Zaretskii <eliz@gnu.org>
parents:
97349
diff
changeset
|
2750 @dfn{context diff format} produced by the @option{-c} or |
18156178166e
(Log Buffer, Diff Mode): Fix last changes. Add indexing.
Eli Zaretskii <eliz@gnu.org>
parents:
97349
diff
changeset
|
2751 @option{--context} options to @command{diff}, first convert the buffer |
18156178166e
(Log Buffer, Diff Mode): Fix last changes. Add indexing.
Eli Zaretskii <eliz@gnu.org>
parents:
97349
diff
changeset
|
2752 to the unified diff format with @kbd{C-c C-u}. |
18156178166e
(Log Buffer, Diff Mode): Fix last changes. Add indexing.
Eli Zaretskii <eliz@gnu.org>
parents:
97349
diff
changeset
|
2753 |
18156178166e
(Log Buffer, Diff Mode): Fix last changes. Add indexing.
Eli Zaretskii <eliz@gnu.org>
parents:
97349
diff
changeset
|
2754 @item C-c C-d |
18156178166e
(Log Buffer, Diff Mode): Fix last changes. Add indexing.
Eli Zaretskii <eliz@gnu.org>
parents:
97349
diff
changeset
|
2755 @findex diff-unified->context |
18156178166e
(Log Buffer, Diff Mode): Fix last changes. Add indexing.
Eli Zaretskii <eliz@gnu.org>
parents:
97349
diff
changeset
|
2756 Convert the entire buffer to the @dfn{context diff format} |
97357
0e44a126b239
(Diff Mode): Fix last change.
Eli Zaretskii <eliz@gnu.org>
parents:
97355
diff
changeset
|
2757 (@code{diff-unified->context}). With a prefix argument, convert only |
97355
18156178166e
(Log Buffer, Diff Mode): Fix last changes. Add indexing.
Eli Zaretskii <eliz@gnu.org>
parents:
97349
diff
changeset
|
2758 the text within the region. |
84239 | 2759 |
2760 @item C-c C-u | |
97355
18156178166e
(Log Buffer, Diff Mode): Fix last changes. Add indexing.
Eli Zaretskii <eliz@gnu.org>
parents:
97349
diff
changeset
|
2761 @findex diff-context->unified |
18156178166e
(Log Buffer, Diff Mode): Fix last changes. Add indexing.
Eli Zaretskii <eliz@gnu.org>
parents:
97349
diff
changeset
|
2762 Convert the entire buffer to unified diff format |
84239 | 2763 (@code{diff-context->unified}). With a prefix argument, convert |
93352
3e6309763b5d
(Diff Mode, Misc File Ops): Describe Transient Mark mode as the
Chong Yidong <cyd@stupidchicken.com>
parents:
87903
diff
changeset
|
2764 unified format to context format. When the mark is active, convert |
3e6309763b5d
(Diff Mode, Misc File Ops): Describe Transient Mark mode as the
Chong Yidong <cyd@stupidchicken.com>
parents:
87903
diff
changeset
|
2765 only the text within the region. |
84239 | 2766 |
2767 @item C-c C-w | |
97355
18156178166e
(Log Buffer, Diff Mode): Fix last changes. Add indexing.
Eli Zaretskii <eliz@gnu.org>
parents:
97349
diff
changeset
|
2768 @findex diff-refine-hunk |
84239 | 2769 Refine the current hunk so that it disregards changes in whitespace |
2770 (@code{diff-refine-hunk}). | |
97349
71b3b925a155
(Log Buffer): Describe C-c C-d.
Dan Nicolaescu <dann@ics.uci.edu>
parents:
97331
diff
changeset
|
2771 |
71b3b925a155
(Log Buffer): Describe C-c C-d.
Dan Nicolaescu <dann@ics.uci.edu>
parents:
97331
diff
changeset
|
2772 @item C-x 4 A |
97355
18156178166e
(Log Buffer, Diff Mode): Fix last changes. Add indexing.
Eli Zaretskii <eliz@gnu.org>
parents:
97349
diff
changeset
|
2773 @findex diff-add-change-log-entries-other-window |
97358
3796d1f0310a
(Diff Mode): Fix indexing in last change.
Eli Zaretskii <eliz@gnu.org>
parents:
97357
diff
changeset
|
2774 @findex add-change-log-entry-other-window@r{, in Diff mode} |
97355
18156178166e
(Log Buffer, Diff Mode): Fix last changes. Add indexing.
Eli Zaretskii <eliz@gnu.org>
parents:
97349
diff
changeset
|
2775 Generate a ChangeLog entry, like @kbd{C-x 4 a} does (@pxref{Change |
18156178166e
(Log Buffer, Diff Mode): Fix last changes. Add indexing.
Eli Zaretskii <eliz@gnu.org>
parents:
97349
diff
changeset
|
2776 Log}), for each one of the hunks |
18156178166e
(Log Buffer, Diff Mode): Fix last changes. Add indexing.
Eli Zaretskii <eliz@gnu.org>
parents:
97349
diff
changeset
|
2777 (@code{diff-add-change-log-entries-other-window}). This creates a |
18156178166e
(Log Buffer, Diff Mode): Fix last changes. Add indexing.
Eli Zaretskii <eliz@gnu.org>
parents:
97349
diff
changeset
|
2778 skeleton of the log of changes that you can later fill with the actual |
18156178166e
(Log Buffer, Diff Mode): Fix last changes. Add indexing.
Eli Zaretskii <eliz@gnu.org>
parents:
97349
diff
changeset
|
2779 descriptions of the changes. @kbd{C-x 4 a} itself in Diff mode |
18156178166e
(Log Buffer, Diff Mode): Fix last changes. Add indexing.
Eli Zaretskii <eliz@gnu.org>
parents:
97349
diff
changeset
|
2780 operates on behalf of the current hunk's file, but gets the function |
18156178166e
(Log Buffer, Diff Mode): Fix last changes. Add indexing.
Eli Zaretskii <eliz@gnu.org>
parents:
97349
diff
changeset
|
2781 name from the patch itself. This is useful for making log entries for |
18156178166e
(Log Buffer, Diff Mode): Fix last changes. Add indexing.
Eli Zaretskii <eliz@gnu.org>
parents:
97349
diff
changeset
|
2782 functions that are deleted by the patch. |
99013
e05e58449b6e
(Diff Mode): Document diff-show-trailing-whitespaces.
Chong Yidong <cyd@stupidchicken.com>
parents:
99011
diff
changeset
|
2783 |
e05e58449b6e
(Diff Mode): Document diff-show-trailing-whitespaces.
Chong Yidong <cyd@stupidchicken.com>
parents:
99011
diff
changeset
|
2784 @item M-x diff-show-trailing-whitespaces RET |
e05e58449b6e
(Diff Mode): Document diff-show-trailing-whitespaces.
Chong Yidong <cyd@stupidchicken.com>
parents:
99011
diff
changeset
|
2785 @findex diff-show-trailing-whitespaces |
99015 | 2786 Highlight trailing whitespace characters, except for those used by the |
2787 patch syntax (@pxref{Useless Whitespace}). | |
84239 | 2788 @end table |
2789 | |
2790 | |
2791 @node Misc File Ops | |
2792 @section Miscellaneous File Operations | |
2793 | |
2794 Emacs has commands for performing many other operations on files. | |
2795 All operate on one file; they do not accept wildcard file names. | |
2796 | |
2797 @findex view-file | |
2798 @cindex viewing | |
2799 @cindex View mode | |
2800 @cindex mode, View | |
2801 @kbd{M-x view-file} allows you to scan or read a file by sequential | |
2802 screenfuls. It reads a file name argument using the minibuffer. After | |
2803 reading the file into an Emacs buffer, @code{view-file} displays the | |
2804 beginning. You can then type @key{SPC} to scroll forward one windowful, | |
2805 or @key{DEL} to scroll backward. Various other commands are provided | |
2806 for moving around in the file, but none for changing it; type @kbd{?} | |
2807 while viewing for a list of them. They are mostly the same as normal | |
2808 Emacs cursor motion commands. To exit from viewing, type @kbd{q}. | |
2809 The commands for viewing are defined by a special minor mode called View | |
2810 mode. | |
2811 | |
2812 A related command, @kbd{M-x view-buffer}, views a buffer already present | |
2813 in Emacs. @xref{Misc Buffer}. | |
2814 | |
2815 @kindex C-x i | |
2816 @findex insert-file | |
2817 @kbd{M-x insert-file} (also @kbd{C-x i}) inserts a copy of the | |
2818 contents of the specified file into the current buffer at point, | |
93352
3e6309763b5d
(Diff Mode, Misc File Ops): Describe Transient Mark mode as the
Chong Yidong <cyd@stupidchicken.com>
parents:
87903
diff
changeset
|
2819 leaving point unchanged before the contents. The position after the |
3e6309763b5d
(Diff Mode, Misc File Ops): Describe Transient Mark mode as the
Chong Yidong <cyd@stupidchicken.com>
parents:
87903
diff
changeset
|
2820 inserted contents is added to the mark ring, without activating the |
3e6309763b5d
(Diff Mode, Misc File Ops): Describe Transient Mark mode as the
Chong Yidong <cyd@stupidchicken.com>
parents:
87903
diff
changeset
|
2821 mark (@pxref{Mark Ring}). |
84239 | 2822 |
2823 @findex insert-file-literally | |
2824 @kbd{M-x insert-file-literally} is like @kbd{M-x insert-file}, | |
2825 except the file is inserted ``literally'': it is treated as a sequence | |
2826 of @acronym{ASCII} characters with no special encoding or conversion, | |
2827 similar to the @kbd{M-x find-file-literally} command | |
2828 (@pxref{Visiting}). | |
2829 | |
2830 @findex write-region | |
2831 @kbd{M-x write-region} is the inverse of @kbd{M-x insert-file}; it | |
2832 copies the contents of the region into the specified file. @kbd{M-x | |
2833 append-to-file} adds the text of the region to the end of the | |
2834 specified file. @xref{Accumulating Text}. The variable | |
2835 @code{write-region-inhibit-fsync} applies to these commands, as well | |
2836 as saving files; see @ref{Customize Save}. | |
2837 | |
2838 @findex delete-file | |
2839 @cindex deletion (of files) | |
2840 @kbd{M-x delete-file} deletes the specified file, like the @code{rm} | |
2841 command in the shell. If you are deleting many files in one directory, it | |
2842 may be more convenient to use Dired (@pxref{Dired}). | |
2843 | |
2844 @findex rename-file | |
2845 @kbd{M-x rename-file} reads two file names @var{old} and @var{new} using | |
2846 the minibuffer, then renames file @var{old} as @var{new}. If the file name | |
2847 @var{new} already exists, you must confirm with @kbd{yes} or renaming is not | |
2848 done; this is because renaming causes the old meaning of the name @var{new} | |
2849 to be lost. If @var{old} and @var{new} are on different file systems, the | |
2850 file @var{old} is copied and deleted. | |
2851 | |
2852 If the argument @var{new} is just a directory name, the real new | |
2853 name is in that directory, with the same non-directory component as | |
2854 @var{old}. For example, @kbd{M-x rename-file RET ~/foo RET /tmp RET} | |
2855 renames @file{~/foo} to @file{/tmp/foo}. The same rule applies to all | |
2856 the remaining commands in this section. All of them ask for | |
2857 confirmation when the new file name already exists, too. | |
2858 | |
2859 @findex add-name-to-file | |
2860 @cindex hard links (creation) | |
2861 The similar command @kbd{M-x add-name-to-file} is used to add an | |
2862 additional name to an existing file without removing its old name. | |
2863 The new name is created as a ``hard link'' to the existing file. | |
2864 The new name must belong on the same file system that the file is on. | |
2865 On MS-Windows, this command works only if the file resides in an NTFS | |
2866 file system. On MS-DOS, it works by copying the file. | |
2867 | |
2868 @findex copy-file | |
2869 @cindex copying files | |
2870 @kbd{M-x copy-file} reads the file @var{old} and writes a new file | |
2871 named @var{new} with the same contents. | |
2872 | |
2873 @findex make-symbolic-link | |
2874 @cindex symbolic links (creation) | |
2875 @kbd{M-x make-symbolic-link} reads two file names @var{target} and | |
2876 @var{linkname}, then creates a symbolic link named @var{linkname}, | |
2877 which points at @var{target}. The effect is that future attempts to | |
2878 open file @var{linkname} will refer to whatever file is named | |
2879 @var{target} at the time the opening is done, or will get an error if | |
2880 the name @var{target} is nonexistent at that time. This command does | |
2881 not expand the argument @var{target}, so that it allows you to specify | |
2882 a relative name as the target of the link. | |
2883 | |
2884 Not all systems support symbolic links; on systems that don't | |
2885 support them, this command is not defined. | |
2886 | |
2887 @node Compressed Files | |
2888 @section Accessing Compressed Files | |
2889 @cindex compression | |
2890 @cindex uncompression | |
2891 @cindex Auto Compression mode | |
2892 @cindex mode, Auto Compression | |
2893 @pindex gzip | |
2894 | |
2895 Emacs automatically uncompresses compressed files when you visit | |
2896 them, and automatically recompresses them if you alter them and save | |
2897 them. Emacs recognizes compressed files by their file names. File | |
2898 names ending in @samp{.gz} indicate a file compressed with | |
2899 @code{gzip}. Other endings indicate other compression programs. | |
2900 | |
2901 Automatic uncompression and compression apply to all the operations in | |
2902 which Emacs uses the contents of a file. This includes visiting it, | |
2903 saving it, inserting its contents into a buffer, loading it, and byte | |
2904 compiling it. | |
2905 | |
2906 @findex auto-compression-mode | |
2907 @vindex auto-compression-mode | |
2908 To disable this feature, type the command @kbd{M-x | |
2909 auto-compression-mode}. You can disable it permanently by | |
2910 customizing the variable @code{auto-compression-mode}. | |
2911 | |
2912 @node File Archives | |
2913 @section File Archives | |
2914 @cindex mode, tar | |
2915 @cindex Tar mode | |
2916 @cindex file archives | |
2917 | |
2918 A file whose name ends in @samp{.tar} is normally an @dfn{archive} | |
2919 made by the @code{tar} program. Emacs views these files in a special | |
2920 mode called Tar mode which provides a Dired-like list of the contents | |
2921 (@pxref{Dired}). You can move around through the list just as you | |
2922 would in Dired, and visit the subfiles contained in the archive. | |
2923 However, not all Dired commands are available in Tar mode. | |
2924 | |
2925 If Auto Compression mode is enabled (@pxref{Compressed Files}), then | |
2926 Tar mode is used also for compressed archives---files with extensions | |
2927 @samp{.tgz}, @code{.tar.Z} and @code{.tar.gz}. | |
2928 | |
2929 The keys @kbd{e}, @kbd{f} and @key{RET} all extract a component file | |
2930 into its own buffer. You can edit it there, and if you save the | |
2931 buffer, the edited version will replace the version in the Tar buffer. | |
2932 @kbd{v} extracts a file into a buffer in View mode. @kbd{o} extracts | |
2933 the file and displays it in another window, so you could edit the file | |
2934 and operate on the archive simultaneously. @kbd{d} marks a file for | |
2935 deletion when you later use @kbd{x}, and @kbd{u} unmarks a file, as in | |
2936 Dired. @kbd{C} copies a file from the archive to disk and @kbd{R} | |
2937 renames a file within the archive. @kbd{g} reverts the buffer from | |
2938 the archive on disk. | |
2939 | |
2940 The keys @kbd{M}, @kbd{G}, and @kbd{O} change the file's permission | |
2941 bits, group, and owner, respectively. | |
2942 | |
2943 If your display supports colors and the mouse, moving the mouse | |
2944 pointer across a file name highlights that file name, indicating that | |
2945 you can click on it. Clicking @kbd{Mouse-2} on the highlighted file | |
2946 name extracts the file into a buffer and displays that buffer. | |
2947 | |
2948 Saving the Tar buffer writes a new version of the archive to disk with | |
2949 the changes you made to the components. | |
2950 | |
2951 You don't need the @code{tar} program to use Tar mode---Emacs reads | |
2952 the archives directly. However, accessing compressed archives | |
2953 requires the appropriate uncompression program. | |
2954 | |
2955 @cindex Archive mode | |
2956 @cindex mode, archive | |
2957 @cindex @code{arc} | |
2958 @cindex @code{jar} | |
99011
5d3f807c7d3e
(Comparing Files): Note that diff uses the minibuffer, and
Chong Yidong <cyd@stupidchicken.com>
parents:
99002
diff
changeset
|
2959 @cindex @code{rar} |
84239 | 2960 @cindex @code{zip} |
2961 @cindex @code{lzh} | |
2962 @cindex @code{zoo} | |
2963 @pindex arc | |
2964 @pindex jar | |
2965 @pindex zip | |
99011
5d3f807c7d3e
(Comparing Files): Note that diff uses the minibuffer, and
Chong Yidong <cyd@stupidchicken.com>
parents:
99002
diff
changeset
|
2966 @pindex rar |
84239 | 2967 @pindex lzh |
2968 @pindex zoo | |
2969 @cindex Java class archives | |
2970 @cindex unzip archives | |
2971 A separate but similar Archive mode is used for archives produced by | |
99011
5d3f807c7d3e
(Comparing Files): Note that diff uses the minibuffer, and
Chong Yidong <cyd@stupidchicken.com>
parents:
99002
diff
changeset
|
2972 the programs @code{arc}, @code{jar}, @code{lzh}, @code{zip}, |
5d3f807c7d3e
(Comparing Files): Note that diff uses the minibuffer, and
Chong Yidong <cyd@stupidchicken.com>
parents:
99002
diff
changeset
|
2973 @code{rar}, and @code{zoo}, which have extensions corresponding to the |
5d3f807c7d3e
(Comparing Files): Note that diff uses the minibuffer, and
Chong Yidong <cyd@stupidchicken.com>
parents:
99002
diff
changeset
|
2974 program names. Archive mode also works for those @code{exe} files |
5d3f807c7d3e
(Comparing Files): Note that diff uses the minibuffer, and
Chong Yidong <cyd@stupidchicken.com>
parents:
99002
diff
changeset
|
2975 that are self-extracting executables. |
84239 | 2976 |
2977 The key bindings of Archive mode are similar to those in Tar mode, | |
2978 with the addition of the @kbd{m} key which marks a file for subsequent | |
2979 operations, and @kbd{M-@key{DEL}} which unmarks all the marked files. | |
2980 Also, the @kbd{a} key toggles the display of detailed file | |
2981 information, for those archive types where it won't fit in a single | |
2982 line. Operations such as renaming a subfile, or changing its mode or | |
2983 owner, are supported only for some of the archive formats. | |
2984 | |
2985 Unlike Tar mode, Archive mode runs the archiving program to unpack | |
2986 and repack archives. Details of the program names and their options | |
2987 can be set in the @samp{Archive} Customize group. However, you don't | |
2988 need these programs to look at the archive table of contents, only to | |
2989 extract or manipulate the subfiles in the archive. | |
2990 | |
2991 @node Remote Files | |
2992 @section Remote Files | |
2993 | |
2994 @cindex Tramp | |
2995 @cindex FTP | |
2996 @cindex remote file access | |
2997 You can refer to files on other machines using a special file name | |
2998 syntax: | |
2999 | |
3000 @example | |
3001 @group | |
3002 /@var{host}:@var{filename} | |
3003 /@var{user}@@@var{host}:@var{filename} | |
3004 /@var{user}@@@var{host}#@var{port}:@var{filename} | |
3005 /@var{method}:@var{user}@@@var{host}:@var{filename} | |
3006 /@var{method}:@var{user}@@@var{host}#@var{port}:@var{filename} | |
3007 @end group | |
3008 @end example | |
3009 | |
3010 @noindent | |
99011
5d3f807c7d3e
(Comparing Files): Note that diff uses the minibuffer, and
Chong Yidong <cyd@stupidchicken.com>
parents:
99002
diff
changeset
|
3011 To carry out this request, Emacs uses a remote-login program such as |
5d3f807c7d3e
(Comparing Files): Note that diff uses the minibuffer, and
Chong Yidong <cyd@stupidchicken.com>
parents:
99002
diff
changeset
|
3012 @command{ftp}, @command{ssh}, @command{rlogin}, or @command{telnet}. |
5d3f807c7d3e
(Comparing Files): Note that diff uses the minibuffer, and
Chong Yidong <cyd@stupidchicken.com>
parents:
99002
diff
changeset
|
3013 You can always specify in the file name which method to use---for |
5d3f807c7d3e
(Comparing Files): Note that diff uses the minibuffer, and
Chong Yidong <cyd@stupidchicken.com>
parents:
99002
diff
changeset
|
3014 example, @file{/ftp:@var{user}@@@var{host}:@var{filename}} uses FTP, |
5d3f807c7d3e
(Comparing Files): Note that diff uses the minibuffer, and
Chong Yidong <cyd@stupidchicken.com>
parents:
99002
diff
changeset
|
3015 whereas @file{/ssh:@var{user}@@@var{host}:@var{filename}} uses |
5d3f807c7d3e
(Comparing Files): Note that diff uses the minibuffer, and
Chong Yidong <cyd@stupidchicken.com>
parents:
99002
diff
changeset
|
3016 @command{ssh}. When you don't specify a method in the file name, |
5d3f807c7d3e
(Comparing Files): Note that diff uses the minibuffer, and
Chong Yidong <cyd@stupidchicken.com>
parents:
99002
diff
changeset
|
3017 Emacs chooses the method as follows: |
84239 | 3018 |
3019 @enumerate | |
3020 @item | |
3021 If the host name starts with @samp{ftp.} (with dot), then Emacs uses | |
3022 FTP. | |
3023 @item | |
3024 If the user name is @samp{ftp} or @samp{anonymous}, then Emacs uses | |
3025 FTP. | |
3026 @item | |
3027 Otherwise, Emacs uses @command{ssh}. | |
3028 @end enumerate | |
3029 | |
3030 @noindent | |
3031 Remote file access through FTP is handled by the Ange-FTP package, which | |
3032 is documented in the following. Remote file access through the other | |
3033 methods is handled by the Tramp package, which has its own manual. | |
3034 @xref{Top, The Tramp Manual,, tramp, The Tramp Manual}. | |
3035 | |
3036 When the Ange-FTP package is used, Emacs logs in through FTP using your | |
3037 user name or the name @var{user}. It may ask you for a password from | |
3038 time to time; this is used for logging in on @var{host}. The form using | |
3039 @var{port} allows you to access servers running on a non-default TCP | |
3040 port. | |
3041 | |
3042 @cindex backups for remote files | |
3043 @vindex ange-ftp-make-backup-files | |
3044 If you want to disable backups for remote files, set the variable | |
3045 @code{ange-ftp-make-backup-files} to @code{nil}. | |
3046 | |
3047 By default, the auto-save files (@pxref{Auto Save Files}) for remote | |
3048 files are made in the temporary file directory on the local machine. | |
3049 This is achieved using the variable @code{auto-save-file-name-transforms}. | |
3050 | |
3051 @cindex ange-ftp | |
3052 @vindex ange-ftp-default-user | |
3053 @cindex user name for remote file access | |
3054 Normally, if you do not specify a user name in a remote file name, | |
3055 that means to use your own user name. But if you set the variable | |
3056 @code{ange-ftp-default-user} to a string, that string is used instead. | |
3057 | |
3058 @cindex anonymous FTP | |
3059 @vindex ange-ftp-generate-anonymous-password | |
3060 To visit files accessible by anonymous FTP, you use special user | |
3061 names @samp{anonymous} or @samp{ftp}. Passwords for these user names | |
3062 are handled specially. The variable | |
3063 @code{ange-ftp-generate-anonymous-password} controls what happens: if | |
3064 the value of this variable is a string, then that string is used as | |
3065 the password; if non-@code{nil} (the default), then the value of | |
3066 @code{user-mail-address} is used; if @code{nil}, then Emacs prompts | |
3067 you for a password as usual. | |
3068 | |
3069 @cindex firewall, and accessing remote files | |
3070 @cindex gateway, and remote file access with @code{ange-ftp} | |
3071 @vindex ange-ftp-smart-gateway | |
3072 @vindex ange-ftp-gateway-host | |
3073 Sometimes you may be unable to access files on a remote machine | |
3074 because a @dfn{firewall} in between blocks the connection for security | |
3075 reasons. If you can log in on a @dfn{gateway} machine from which the | |
3076 target files @emph{are} accessible, and whose FTP server supports | |
3077 gatewaying features, you can still use remote file names; all you have | |
3078 to do is specify the name of the gateway machine by setting the | |
3079 variable @code{ange-ftp-gateway-host}, and set | |
3080 @code{ange-ftp-smart-gateway} to @code{t}. Otherwise you may be able | |
3081 to make remote file names work, but the procedure is complex. You can | |
3082 read the instructions by typing @kbd{M-x finder-commentary @key{RET} | |
3083 ange-ftp @key{RET}}. | |
3084 | |
3085 @vindex file-name-handler-alist | |
3086 @cindex disabling remote files | |
3087 You can entirely turn off the FTP file name feature by removing the | |
3088 entries @code{ange-ftp-completion-hook-function} and | |
3089 @code{ange-ftp-hook-function} from the variable | |
3090 @code{file-name-handler-alist}. You can turn off the feature in | |
3091 individual cases by quoting the file name with @samp{/:} (@pxref{Quoted | |
3092 File Names}). | |
3093 | |
3094 @node Quoted File Names | |
3095 @section Quoted File Names | |
3096 | |
3097 @cindex quoting file names | |
3098 @cindex file names, quote special characters | |
3099 You can @dfn{quote} an absolute file name to prevent special | |
3100 characters and syntax in it from having their special effects. | |
3101 The way to do this is to add @samp{/:} at the beginning. | |
3102 | |
3103 For example, you can quote a local file name which appears remote, to | |
3104 prevent it from being treated as a remote file name. Thus, if you have | |
3105 a directory named @file{/foo:} and a file named @file{bar} in it, you | |
3106 can refer to that file in Emacs as @samp{/:/foo:/bar}. | |
3107 | |
3108 @samp{/:} can also prevent @samp{~} from being treated as a special | |
3109 character for a user's home directory. For example, @file{/:/tmp/~hack} | |
3110 refers to a file whose name is @file{~hack} in directory @file{/tmp}. | |
3111 | |
3112 Quoting with @samp{/:} is also a way to enter in the minibuffer a | |
3113 file name that contains @samp{$}. In order for this to work, the | |
3114 @samp{/:} must be at the beginning of the minibuffer contents. (You | |
3115 can also double each @samp{$}; see @ref{File Names with $}.) | |
3116 | |
3117 You can also quote wildcard characters with @samp{/:}, for visiting. | |
3118 For example, @file{/:/tmp/foo*bar} visits the file | |
3119 @file{/tmp/foo*bar}. | |
3120 | |
3121 Another method of getting the same result is to enter | |
3122 @file{/tmp/foo[*]bar}, which is a wildcard specification that matches | |
3123 only @file{/tmp/foo*bar}. However, in many cases there is no need to | |
3124 quote the wildcard characters because even unquoted they give the | |
3125 right result. For example, if the only file name in @file{/tmp} that | |
3126 starts with @samp{foo} and ends with @samp{bar} is @file{foo*bar}, | |
3127 then specifying @file{/tmp/foo*bar} will visit only | |
3128 @file{/tmp/foo*bar}. | |
3129 | |
3130 @node File Name Cache | |
3131 @section File Name Cache | |
3132 | |
3133 @cindex file name caching | |
3134 @cindex cache of file names | |
3135 @pindex find | |
3136 @kindex C-@key{TAB} | |
3137 @findex file-cache-minibuffer-complete | |
3138 You can use the @dfn{file name cache} to make it easy to locate a | |
3139 file by name, without having to remember exactly where it is located. | |
3140 When typing a file name in the minibuffer, @kbd{C-@key{tab}} | |
3141 (@code{file-cache-minibuffer-complete}) completes it using the file | |
3142 name cache. If you repeat @kbd{C-@key{tab}}, that cycles through the | |
3143 possible completions of what you had originally typed. (However, note | |
3144 that the @kbd{C-@key{tab}} character cannot be typed on most text-only | |
3145 terminals.) | |
3146 | |
3147 The file name cache does not fill up automatically. Instead, you | |
3148 load file names into the cache using these commands: | |
3149 | |
3150 @findex file-cache-add-directory | |
3151 @table @kbd | |
3152 @item M-x file-cache-add-directory @key{RET} @var{directory} @key{RET} | |
3153 Add each file name in @var{directory} to the file name cache. | |
3154 @item M-x file-cache-add-directory-using-find @key{RET} @var{directory} @key{RET} | |
3155 Add each file name in @var{directory} and all of its nested | |
3156 subdirectories to the file name cache. | |
3157 @item M-x file-cache-add-directory-using-locate @key{RET} @var{directory} @key{RET} | |
3158 Add each file name in @var{directory} and all of its nested | |
3159 subdirectories to the file name cache, using @command{locate} to find | |
3160 them all. | |
3161 @item M-x file-cache-add-directory-list @key{RET} @var{variable} @key{RET} | |
3162 Add each file name in each directory listed in @var{variable} | |
3163 to the file name cache. @var{variable} should be a Lisp variable | |
3164 such as @code{load-path} or @code{exec-path}, whose value is a list | |
3165 of directory names. | |
3166 @item M-x file-cache-clear-cache @key{RET} | |
3167 Clear the cache; that is, remove all file names from it. | |
3168 @end table | |
3169 | |
3170 The file name cache is not persistent: it is kept and maintained | |
3171 only for the duration of the Emacs session. You can view the contents | |
3172 of the cache with the @code{file-cache-display} command. | |
3173 | |
3174 @node File Conveniences | |
3175 @section Convenience Features for Finding Files | |
3176 | |
3177 In this section, we introduce some convenient facilities for finding | |
3178 recently-opened files, reading file names from a buffer, and viewing | |
3179 image files. | |
3180 | |
3181 @findex recentf-mode | |
3182 @vindex recentf-mode | |
3183 @findex recentf-save-list | |
3184 @findex recentf-edit-list | |
3185 If you enable Recentf mode, with @kbd{M-x recentf-mode}, the | |
3186 @samp{File} menu includes a submenu containing a list of recently | |
3187 opened files. @kbd{M-x recentf-save-list} saves the current | |
3188 @code{recent-file-list} to a file, and @kbd{M-x recentf-edit-list} | |
3189 edits it. | |
3190 | |
3191 The @kbd{M-x ffap} command generalizes @code{find-file} with more | |
3192 powerful heuristic defaults (@pxref{FFAP}), often based on the text at | |
3193 point. Partial Completion mode offers other features extending | |
3194 @code{find-file}, which can be used with @code{ffap}. | |
3195 @xref{Completion Options}. | |
3196 | |
3197 @findex image-mode | |
3198 @findex image-toggle-display | |
3199 @cindex images, viewing | |
3200 Visiting image files automatically selects Image mode. This major | |
3201 mode allows you to toggle between displaying the file as an image in | |
3202 the Emacs buffer, and displaying its underlying text representation, | |
3203 using the command @kbd{C-c C-c} (@code{image-toggle-display}). This | |
3204 works only when Emacs can display the specific image type. If the | |
3205 displayed image is wider or taller than the frame, the usual point | |
3206 motion keys (@kbd{C-f}, @kbd{C-p}, and so forth) cause different parts | |
3207 of the image to be displayed. | |
3208 | |
3209 @findex thumbs-mode | |
3210 @findex mode, thumbs | |
3211 See also the Image-Dired package (@pxref{Image-Dired}) for viewing | |
3212 images as thumbnails. | |
3213 | |
3214 @node Filesets | |
3215 @section Filesets | |
3216 @cindex filesets | |
3217 | |
3218 @findex filesets-init | |
3219 If you regularly edit a certain group of files, you can define them | |
3220 as a @dfn{fileset}. This lets you perform certain operations, such as | |
3221 visiting, @code{query-replace}, and shell commands on all the files | |
3222 at once. To make use of filesets, you must first add the expression | |
3223 @code{(filesets-init)} to your @file{.emacs} file (@pxref{Init File}). | |
3224 This adds a @samp{Filesets} menu to the menu bar. | |
3225 | |
3226 @findex filesets-add-buffer | |
3227 @findex filesets-remove-buffer | |
3228 The simplest way to define a fileset is by adding files to it one | |
3229 at a time. To add a file to fileset @var{name}, visit the file and | |
3230 type @kbd{M-x filesets-add-buffer @kbd{RET} @var{name} @kbd{RET}}. If | |
3231 there is no fileset @var{name}, this creates a new one, which | |
3232 initially creates only the current file. The command @kbd{M-x | |
3233 filesets-remove-buffer} removes the current file from a fileset. | |
3234 | |
3235 You can also edit the list of filesets directly, with @kbd{M-x | |
3236 filesets-edit} (or by choosing @samp{Edit Filesets} from the | |
3237 @samp{Filesets} menu). The editing is performed in a Customize buffer | |
3238 (@pxref{Easy Customization}). Filesets need not be a simple list of | |
3239 files---you can also define filesets using regular expression matching | |
3240 file names. Some examples of these more complicated filesets are | |
3241 shown in the Customize buffer. Remember to select @samp{Save for | |
3242 future sessions} if you want to use the same filesets in future Emacs | |
3243 sessions. | |
3244 | |
3245 You can use the command @kbd{M-x filesets-open} to visit all the | |
3246 files in a fileset, and @kbd{M-x filesets-close} to close them. Use | |
3247 @kbd{M-x filesets-run-cmd} to run a shell command on all the files in | |
3248 a fileset. These commands are also available from the @samp{Filesets} | |
3249 menu, where each existing fileset is represented by a submenu. | |
3250 | |
85473
21825793865e
Disambiguate two slightly different uses of the term 'filesets'.
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85236
diff
changeset
|
3251 Emacs uses the concept of a fileset elsewhere @pxref{Version |
21825793865e
Disambiguate two slightly different uses of the term 'filesets'.
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85236
diff
changeset
|
3252 Control} to describe sets of files to be treated as a group for |
99002
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
3253 purposes of version control operations. Those filesets are unnamed |
b232f24c023c
(Visiting): Document find-file-confirm-nonexistent-file.
Chong Yidong <cyd@stupidchicken.com>
parents:
98775
diff
changeset
|
3254 and do not persist across Emacs sessions. |
85473
21825793865e
Disambiguate two slightly different uses of the term 'filesets'.
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85236
diff
changeset
|
3255 |
84239 | 3256 @ignore |
3257 arch-tag: 768d32cb-e15a-4cc1-b7bf-62c00ee12250 | |
3258 @end ignore |