1 @c This is part of the Emacs manual.
2 @c Copyright (C) 2004-2018 Free Software Foundation, Inc.
3 @c See file emacs.texi for copying conditions.
5 @c This file is included either in vc-xtra.texi (when producing the
6 @c printed version) or in the main Emacs manual (for the on-line version).
9 @subsection Miscellaneous Commands and Features of VC
11 This section explains the less-frequently-used features of VC.
14 * Change Logs and VC:: Generating a change log file from log entries.
15 * VC Delete/Rename:: Deleting and renaming version-controlled files.
16 * Revision Tags:: Symbolic names for revisions.
17 * Version Headers:: Inserting version control headers into working files.
20 @node Change Logs and VC
21 @subsubsection Change Logs and VC
23 If you use RCS or CVS for a program with a @file{ChangeLog} file
25 (@pxref{Change Log,,,emacs, the Emacs Manual}),
30 you can generate change log entries from the version control log
31 entries of previous commits.
33 Note that this only works with RCS or CVS@. This procedure would be
34 particularly incorrect on a modern changeset-based version control
35 system, where changes to the @file{ChangeLog} file would normally be
36 committed as part of a changeset. In that case, you should write the
37 change log entries first, then pull them into the @samp{*vc-log*}
38 buffer when you commit
40 (@pxref{Log Buffer,,,emacs, the Emacs Manual}).
49 @findex vc-update-change-log
50 Visit the current directory's @file{ChangeLog} file and, for
51 registered files in that directory, create new entries for versions
52 committed since the most recent change log entry
53 (@code{vc-update-change-log}).
56 As above, but only find entries for the current buffer's file.
59 For example, suppose the first line of @file{ChangeLog} is dated
60 1999-04-10, and that the only check-in since then was by Nathaniel
61 Bowditch to @file{rcs2log} on 1999-05-22 with log entry @samp{Ignore
62 log messages that start with '#'.}. Then @kbd{C-x v a} inserts this
63 @file{ChangeLog} entry:
70 1999-05-22 Nathaniel Bowditch <nat@@apn.org>
72 * rcs2log: Ignore log messages that start with '#'.
80 If the version control log entry specifies a function name (in
81 parenthesis at the beginning of a line), that is reflected in the
82 @file{ChangeLog} entry. For example, if a log entry for @file{vc.el}
83 is @samp{(vc-do-command): Check call-process status.}, the
84 @file{ChangeLog} entry is:
91 1999-05-06 Nathaniel Bowditch <nat@@apn.org>
93 * vc.el (vc-do-command): Check call-process status.
100 When @kbd{C-x v a} adds several change log entries at once, it
101 groups related log entries together if they all are checked in by the
102 same author at nearly the same time. If the log entries for several
103 such files all have the same text, it coalesces them into a single
106 @node VC Delete/Rename
107 @subsubsection Deleting and Renaming Version-Controlled Files
108 @cindex renaming version-controlled files
111 @item M-x vc-delete-file
112 Prompt for a file name, delete the file from the working tree, and
113 schedule the deletion for committing.
115 @item M-x vc-rename-file
116 Prompt for two file names, @var{var} and @var{old}, rename them in the
117 working tree, and schedule the renaming for committing.
120 @findex vc-delete-file
121 If you wish to delete a version-controlled file, use the command
122 @kbd{M-x vc-delete-file}. This prompts for the file name, and deletes
123 it via the version control system. The file is removed from the
124 working tree, and in the VC Directory buffer
126 (@pxref{VC Directory Mode,,, emacs, the Emacs Manual}),
129 (@pxref{VC Directory Mode}),
131 it is displayed with the @samp{removed} status. When you commit it,
132 the deletion takes effect in the repository.
134 @findex vc-rename-file
135 To rename a version-controlled file, type @kbd{M-x vc-rename-file}.
136 This prompts for two arguments: the name of the file you wish to
137 rename, and the new name; then it performs the renaming via the
138 version control system. The renaming takes effect immediately in the
139 working tree, and takes effect in the repository when you commit the
142 On modern version control systems that have built-in support for
143 renaming, the renamed file retains the full change history of the
144 original file. On CVS and older version control systems, the
145 @code{vc-rename-file} command actually works by creating a copy of the
146 old file under the new name, registering it, and deleting the old
147 file. In this case, the change history is not preserved.
150 @subsubsection Revision Tags
152 @cindex tags for version control
154 Most version control systems allow you to apply a @dfn{revision tag}
155 to a specific version of a version-controlled tree. On modern
156 changeset-based version control systems, a revision tag is simply a
157 symbolic name for a particular revision. On older file-based systems
158 like CVS, each tag is added to the entire set of version-controlled
159 files, allowing them to be handled as a unit. Revision tags are
160 commonly used to identify releases that are distributed to users.
162 There are two basic commands for tags; one makes a tag with a given
163 name, the other retrieves a named tag.
167 @findex vc-create-tag
168 @item C-x v s @var{name} @key{RET}
169 Define the working revision of every registered file in or under the
170 current directory as a tag named @var{name}
171 (@code{vc-create-tag}).
174 @findex vc-retrieve-tag
175 @item C-x v r @var{name} @key{RET}
176 For all registered files at or below the current directory level,
177 retrieve the tagged revision @var{name}. This command will switch to a
178 branch if @var{name} is a branch name and your VCS distinguishes
179 branches from tags. (@code{vc-retrieve-tag}).
181 This command reports an error if any files are locked at or below the
182 current directory, without changing anything; this is to avoid
183 overwriting work in progress.
186 You can give a tag or branch name as an argument to @kbd{C-x v =} or
189 (@pxref{Old Revisions,,,emacs, the Emacs Manual}).
192 (@pxref{Old Revisions}).
194 Thus, you can use it to compare a tagged version against the current files,
195 or two tagged versions against each other.
197 On SCCS, VC implements tags itself; these tags are visible only
198 through VC@. Most later systems (including CVS, Subversion, bzr, git,
199 and hg) have a native tag facility, and VC uses it where available;
200 those tags will be visible even when you bypass VC.
202 In file-based version control systems, when you rename a registered
203 file you need to rename its master along with it; the command
204 @code{vc-rename-file} will do this automatically
206 (@pxref{VC Delete/Rename,,,emacs, the Emacs Manual}).
209 (@pxref{VC Delete/Rename}).
211 If you are using SCCS, you must also update the records of the tag, to
212 mention the file by its new name (@code{vc-rename-file} does this,
213 too). An old tag that refers to a master file that no longer exists
214 under the recorded name is invalid; VC can no longer retrieve it. It
215 would be beyond the scope of this manual to explain enough about RCS
216 and SCCS to explain how to update the tags by hand. Using
217 @code{vc-rename-file} makes the tag remain valid for retrieval, but it
218 does not solve all problems. For example, some of the files in your
219 program probably refer to others by name. At the very least, the
220 makefile probably mentions the file that you renamed. If you retrieve
221 an old tag, the renamed file is retrieved under its new name, which is
222 not the name that the makefile expects. So the program won't really
225 @node Version Headers
226 @subsubsection Inserting Version Control Headers
228 On Subversion, CVS, RCS, and SCCS, you can put certain special
229 strings called @dfn{version headers} into a work file. When the file
230 is committed, the version control system automatically puts the
231 revision number, the name of the user who made the commit, and other
232 relevant information into the version header.
234 @vindex vc-consult-headers
235 VC does not normally use the information in the version headers. As
236 an exception, when using RCS, Emacs uses the version header, if there
237 is one, to determine the file version, since it is often more reliable
238 than the RCS master file. To inhibit using the version header this
239 way, change the variable @code{vc-consult-headers} to @code{nil}. VC
240 then always uses the file permissions (if it is supposed to trust
241 them), or else checks the master file.
243 @findex vc-insert-headers
244 @vindex vc-@var{backend}-header
245 To insert a suitable header string into the current buffer, use the
246 command @kbd{M-x vc-insert-headers}. This command works only on
247 Subversion, CVS, RCS, and SCCS@. The variable
248 @code{vc-@var{backend}-header} contains the list of keywords to insert
249 into the version header; for instance, CVS uses @code{vc-cvs-header},
250 whose default value is @code{'("\$Id\$")}. (The extra backslashes
251 prevent the string constant from being interpreted as a header, if the
252 Emacs Lisp file defining it is maintained with version control.) The
253 @code{vc-insert-headers} command inserts each keyword in the list on a
254 new line at point, surrounded by tabs, and inside comment delimiters
257 @vindex vc-static-header-alist
258 The variable @code{vc-static-header-alist} specifies further strings
259 to add based on the name of the buffer. Its value should be a list of
260 elements of the form @code{(@var{regexp} . @var{format})}. Whenever
261 @var{regexp} matches the buffer name, @var{format} is also inserted as
262 part of the version header. A @samp{%s} in @var{format} is replaced
263 with the file's version control type.
266 @subsection Customizing VC
268 @vindex vc-handled-backends
269 The variable @code{vc-handled-backends} determines which version
270 control systems VC should handle. The default value is @code{(RCS CVS
271 SVN SCCS Bzr Git Hg Mtn Arch)}, so it contains all the version systems
272 that are currently supported. If you want VC to ignore one or more of
273 these systems, exclude its name from the list. To disable VC
274 entirely, set this variable to @code{nil}.
276 The order of systems in the list is significant: when you visit a
277 file registered in more than one system, VC uses the system that comes
278 first in @code{vc-handled-backends} by default. The order is also
279 significant when you register a file for the first time
281 (@pxref{Registering,,,emacs, the Emacs Manual}).
284 (@pxref{Registering}).
288 * General VC Options:: Options that apply to multiple back ends.
289 * RCS and SCCS:: Options for RCS and SCCS.
290 * CVS Options:: Options for CVS.
293 @node General VC Options
294 @subsubsection General Options
296 @vindex vc-make-backup-files
297 Emacs normally does not save backup files for source files that are
298 maintained with version control. If you want to make backup files even
299 for files that use version control, set the variable
300 @code{vc-make-backup-files} to a non-@code{nil} value.
302 @vindex vc-follow-symlinks
303 @cindex symbolic links (and version control)
304 Editing a version-controlled file through a symbolic link may cause
305 unexpected results, if you are unaware that the underlying file is
306 version-controlled. The variable @code{vc-follow-symlinks} controls
307 what Emacs does if you try to visit a symbolic link pointing to a
308 version-controlled file. If the value is @code{ask} (the default),
309 Emacs asks for confirmation. If it is @code{nil}, Emacs just displays
310 a warning message. If it is @code{t}, Emacs automatically follows the
311 link and visits the real file instead.
313 @vindex vc-suppress-confirm
314 If @code{vc-suppress-confirm} is non-@code{nil}, then @kbd{C-x v v}
315 and @kbd{C-x v i} can save the current buffer without asking, and
316 @kbd{C-x v u} also operates without asking for confirmation.
318 @vindex vc-command-messages
319 VC mode does much of its work by running the shell commands for the
320 appropriate version control system. If @code{vc-command-messages} is
321 non-@code{nil}, VC displays messages to indicate which shell commands
322 it runs, and additional messages when the commands finish.
325 @subsubsection Options for RCS and SCCS
327 @cindex non-strict locking (RCS)
328 @cindex locking, non-strict (RCS)
329 By default, RCS uses locking to coordinate the activities of several
330 users, but there is a mode called @dfn{non-strict locking} in which
331 you can check-in changes without locking the file first. Use
332 @samp{rcs -U} to switch to non-strict locking for a particular file,
333 see the @code{rcs} manual page for details.
335 When deducing the version control state of an RCS file, VC first
336 looks for an RCS version header string in the file (@pxref{Version
337 Headers}). If there is no header string, VC normally looks at the
338 file permissions of the work file; this is fast. But there might be
339 situations when the file permissions cannot be trusted. In this case
340 the master file has to be consulted, which is rather expensive. Also
341 the master file can only tell you @emph{if} there's any lock on the
342 file, but not whether your work file really contains that locked
345 You can tell VC not to use version headers to determine the file
346 status by setting @code{vc-consult-headers} to @code{nil}. VC then
347 always uses the file permissions (if it is supposed to trust them), or
348 else checks the master file.
350 VC determines the version control state of files under SCCS much as
351 with RCS@. It does not consider SCCS version headers, though. Thus,
352 the variable @code{vc-consult-headers} does not affect SCCS use.
355 @subsubsection Options specific for CVS
357 @vindex vc-cvs-global-switches
358 You can specify additional command line options to pass to all CVS
359 operations in the variable @code{vc-cvs-global-switches}. These
360 switches are inserted immediately after the @code{cvs} command, before
361 the name of the operation to invoke.
363 @vindex vc-cvs-stay-local
364 @cindex remote repositories (CVS)
365 When using a CVS repository on a remote machine, VC can try keeping
366 network interactions to a minimum. This is controlled by the variable
367 @code{vc-cvs-stay-local}. If @code{vc-cvs-stay-local} is
368 @code{only-file} (the default), VC determines the version control
369 status of each file using only the entry in the local CVS subdirectory
370 and the information returned by previous CVS commands. As a
371 consequence, if you have modified a file and somebody else has checked
372 in other changes, you will not be notified of the conflict until you
375 If you change @code{vc-cvs-stay-local} to @code{nil}, VC queries the
376 remote repository @emph{before} it decides what to do in
377 @code{vc-next-action} (@kbd{C-x v v}), just as it does for local
380 You can also set @code{vc-cvs-stay-local} to a regular expression
381 that is matched against the repository host name; VC then stays local
382 only for repositories from hosts that match the pattern.
384 @cindex automatic version backups
385 When using a remote repository, Emacs normally makes @dfn{automatic
386 version backups} of the original versions of each edited file. These
387 local backups are made whenever you save the first changes to a file,
388 and they are removed after you commit your changes to the repository.
389 (Note that these are not the same as ordinary Emacs backup files;
391 @pxref{Backup,,,emacs, the Emacs Manual}.)
396 Commands like @kbd{C-x v =} and @kbd{C-x v u} make use of automatic
397 version backups, if possible, to avoid having to access the network.
399 Setting @code{vc-cvs-stay-local} to @code{nil} disables the making
400 of automatic version backups.
402 @cindex manual version backups
403 Automatic version backups have names of the form
404 @w{@code{@var{file}.~@var{version}.~}}. This is similar to the name
405 that @kbd{C-x v ~} saves old versions to
407 (@pxref{Old Revisions,,,emacs, the Emacs Manual}),
410 (@pxref{Old Revisions}),
412 except for the additional dot (@samp{.}) after the version. The
413 relevant VC commands can use both kinds of version backups. The main
414 difference is that the manual version backups made by @kbd{C-x v
415 ~} are not deleted automatically when you commit.
417 @cindex locking (CVS)
418 CVS does not use locking by default, but there are ways to enable
419 locking-like behavior using its @env{CVSREAD} or @dfn{watch} feature;
420 see the CVS documentation for details. If that case, you can use
421 @kbd{C-x v v} in Emacs to toggle locking, as you would for a
422 locking-based version control system
424 (@pxref{VC With A Locking VCS,,,emacs, the Emacs Manual}).
427 (@pxref{VC With A Locking VCS}).