Commit 2785d024 authored by Chong Yidong's avatar Chong Yidong

More updates for VC documentation.

* doc/emacs/vc1-xtra.texi (Version Headers): Note that these are for
Subversion, CVS, etc. only.
(General VC Options): De-document vc-keep-workfiles.  Fix RCS-isms.

* doc/emacs/maintaining.texi (Change Log Commands): Don't specially mention
vc-update-change-log which is CVS-only.
parent 0ab39399
2011-12-22 Chong Yidong <cyd@gnu.org>
* maintaining.texi (Change Log Commands): Don't specially mention
vc-update-change-log which is CVS-only.
* vc1-xtra.texi (Version Headers): Note that these are for
Subversion, CVS, etc. only.
(General VC Options): De-document vc-keep-workfiles. Fix
RCS-isms.
2011-12-22 Eli Zaretskii <eliz@gnu.org>
* building.texi (Debugger Operation): Fix a typo: "@end iftext"
......
......@@ -565,7 +565,7 @@ Mode}). Completion is available for most debugger commands
commands to repeat them.
@iftex
See the next section
@end iftext
@end iftex
@ifnottex
@xref{Commands of GUD},
@end ifnottex
......
......@@ -1438,13 +1438,11 @@ different revision with @kbd{C-u C-x v v}.
@section Change Logs
@cindex change log
A change log file contains a chronological record of when and why you
have changed a program, consisting of a sequence of entries describing
individual changes. Normally it is kept in a file called
@file{ChangeLog} in the same directory as the file you are editing, or
one of its parent directories. A single @file{ChangeLog} file can
record changes for all the files in its directory and all its
subdirectories.
Many software projects keep a @dfn{change log}. This is a file,
normally named @file{ChangeLog}, containing a chronological record of
when and how the program was changed. Sometimes, there are several
change log files, each recording the changes in one directory or
directory tree.
@menu
* Change Log Commands:: Commands for editing change log files.
......@@ -1476,7 +1474,7 @@ rather than starting a new item.
You can combine multiple changes of the same nature. If you don't
enter any text after the initial @kbd{C-x 4 a}, any subsequent
@kbd{C-x 4 a} adds another symbol to the change.
@kbd{C-x 4 a} adds another symbol to the change log entry.
@vindex add-log-always-start-new-record
If @code{add-log-always-start-new-record} is non-@code{nil},
......@@ -1514,15 +1512,7 @@ ordering of entries.
Version control systems are another way to keep track of changes in
your program and keep a change log. In the VC log buffer, typing
@kbd{C-c C-a} (@code{log-edit-insert-changelog}) inserts the relevant
Change Log entry, if one exists (@pxref{Log Buffer}). You can also
insert a VC log entry into a Change Log buffer by typing @kbd{C-x v a}
(@code{vc-update-change-log}) in the Change Log buffer
@iftex
(@pxref{Change Logs and VC,,,emacs-xtra, Specialized Emacs Features}).
@end iftex
@ifnottex
(@pxref{Change Logs and VC}).
@end ifnottex
Change Log entry, if one exists. @xref{Log Buffer}.
@node Format of ChangeLog
@subsection Format of ChangeLog
......
......@@ -204,123 +204,63 @@ So the program won't really work as retrieved.
@node Version Headers
@subsubsection Inserting Version Control Headers
Sometimes it is convenient to put version identification strings
directly into working files. Certain special strings called
@dfn{version headers} are replaced in each successive version by the
number of that version, the name of the user who created it, and other
relevant information. All of the back ends that VC supports have such
a mechanism, except GNU Arch.
VC does not normally use the information contained in these headers.
The exception is RCS---with RCS, version headers are sometimes more
reliable than the master file to determine which version of the file
you are editing.
Searching for RCS version headers is controlled by the variable
@code{vc-consult-headers}. If it is non-@code{nil} (the default),
Emacs searches for headers to determine the version number you are
editing. Setting it to @code{nil} disables this feature.
Note that although CVS uses the same kind of version headers as RCS
does, VC never searches for these headers if you are using CVS,
regardless of the above setting.
On Subversion, CVS, RCS, and SCCS, you can put certain special
strings called @dfn{version headers} into a work file. When the file
is committed, the version control system automatically puts the
revision number, the name of the user who made the commit, and other
relevant information into the version header.
@vindex vc-consult-headers
VC does not normally use the information in the version headers. As
an exception, when using RCS, Emacs uses the version header, if there
is one, to determine the file version, since it is often more reliable
than the RCS master file. To inhibit using the version header this
way, change the variable @code{vc-consult-headers} to @code{nil}.
@kindex C-x v h
@findex vc-insert-headers
You can use the @kbd{C-x v h} command (@code{vc-insert-headers}) to
insert a suitable header string.
@table @kbd
@item C-x v h
Insert headers in a file for use with your version-control system.
@end table
@vindex vc-@var{backend}-header
The default header string is @samp{@w{$}Id$} for RCS and
@samp{@w{%}W%} for SCCS. You can specify other headers to insert by
setting the variables @code{vc-@var{backend}-header} where
@var{backend} is @code{rcs} or @code{sccs}.
Instead of a single string, you can specify a list of strings; then
each string in the list is inserted as a separate header on a line of
its own.
It may be necessary to use apparently-superfluous backslashes when
writing the strings that you put in this variable. For instance, you
might write @code{"$Id\$"} rather than @code{"$Id@w{$}"}. The extra
backslash prevents the string constant from being interpreted as a
header, if the Emacs Lisp file containing it is maintained with
version control.
@vindex vc-comment-alist
Each header is inserted surrounded by tabs, inside comment delimiters,
on a new line at point. Normally the ordinary comment
start and comment end strings of the current mode are used, but for
certain modes, there are special comment delimiters for this purpose;
the variable @code{vc-comment-alist} specifies them. Each element of
this list has the form @code{(@var{mode} @var{starter} @var{ender})}.
To insert a suitable header string into the current buffer, type
@kbd{C-x v h} (@code{vc-insert-headers}). This command works only on
Subversion, CVS, RCS, and SCCS. The variable
@code{vc-@var{backend}-header} contains the list of keywords to insert
into the version header; for instance, CVS uses @code{vc-cvs-header},
whose default value is @code{'("\$Id\$")}. (The extra backslashes
prevent the string constant from being interpreted as a header, if the
Emacs Lisp file defining it is maintained with version control.) The
@kbd{C-x v h} command inserts each keyword in the list on a new line
at point, surrounded by tabs, and inside comment delimiters if
necessary.
@vindex vc-static-header-alist
The variable @code{vc-static-header-alist} specifies further strings
to add based on the name of the buffer. Its value should be a list of
elements of the form @code{(@var{regexp} . @var{format})}. Whenever
@var{regexp} matches the buffer name, @var{format} is inserted as part
of the header. A header line is inserted for each element that matches
the buffer name, and for each string specified by
@code{vc-@var{backend}-header}. The header line is made by processing the
string from @code{vc-@var{backend}-header} with the format taken from the
element. The default value for @code{vc-static-header-alist} is as follows:
@example
@group
(("\\.c$" .
"\n#ifndef lint\nstatic char vcid[] = \"\%s\";\n\
#endif /* lint */\n"))
@end group
@end example
@noindent
It specifies insertion of text of this form:
@example
@group
#ifndef lint
static char vcid[] = "@var{string}";
#endif /* lint */
@end group
@end example
@noindent
Note that the text above starts with a blank line.
If you use more than one version header in a file, put them close
together in the file. The mechanism in @code{revert-buffer} that
preserves markers may not handle markers positioned between two version
headers.
@var{regexp} matches the buffer name, @var{format} is also inserted as
part of the version header. A @samp{%s} in @var{format} is replaced
with the file's version control type.
@node Customizing VC
@subsection Customizing VC
@vindex vc-handled-backends
The variable @code{vc-handled-backends} determines which version
The variable @code{vc-handled-backends} determines which version
control systems VC should handle. The default value is @code{(RCS CVS
SVN SCCS Bzr Git Hg Mtn Arch)}, so it contains all the version systems
that are currently supported. If you want VC to ignore one or more of
these systems, exclude its name from the list. To disable VC entirely,
set this variable to @code{nil}.
these systems, exclude its name from the list. To disable VC
entirely, set this variable to @code{nil}.
The order of systems in the list is significant: when you visit a file
registered in more than one system, VC uses the system that comes
The order of systems in the list is significant: when you visit a
file registered in more than one system, VC uses the system that comes
first in @code{vc-handled-backends} by default. The order is also
significant when you register a file for the first time, see
significant when you register a file for the first time
@iftex
@ref{Registering,,,emacs, the Emacs Manual},
(@pxref{Registering,,,emacs, the Emacs Manual}).
@end iftex
@ifnottex
@ref{Registering},
(@pxref{Registering}).
@end ifnottex
for details.
@menu
* General VC Options:: Options that apply to multiple back ends.
......@@ -337,40 +277,27 @@ maintained with version control. If you want to make backup files even
for files that use version control, set the variable
@code{vc-make-backup-files} to a non-@code{nil} value.
@vindex vc-keep-workfiles
Normally the work file exists all the time, whether it is locked or
not. If you set @code{vc-keep-workfiles} to @code{nil}, then checking
in a new version with @kbd{C-x v v} deletes the work file; but any
attempt to visit the file with Emacs creates it again. (With CVS, work
files are always kept.)
@vindex vc-follow-symlinks
Editing a version-controlled file through a symbolic link can be
dangerous. It bypasses the version control system---you can edit the
file without locking it, and fail to check your changes in. Also,
your changes might overwrite those of another user. To protect against
this, VC checks each symbolic link that you visit, to see if it points
to a file under version control.
The variable @code{vc-follow-symlinks} controls what to do when a
symbolic link points to a version-controlled file. If it is @code{nil},
VC only displays a warning message. If it is @code{t}, VC automatically
follows the link, and visits the real file instead, telling you about
this in the echo area. If the value is @code{ask} (the default), VC
asks you each time whether to follow the link.
@cindex symbolic links (and version control)
Editing a version-controlled file through a symbolic link may cause
unexpected results, if you are unaware that the underlying file is
version-controlled. The variable @code{vc-follow-symlinks} controls
what Emacs does if you try to visit a symbolic link pointing to a
version-controlled file. If the value is @code{ask} (the default),
Emacs asks for confirmation. If it is @code{nil}, Emacs just displays
a warning message. If it is @code{t}, Emacs automatically follows the
link and visits the real file instead.
@vindex vc-suppress-confirm
If @code{vc-suppress-confirm} is non-@code{nil}, then @kbd{C-x v v}
and @kbd{C-x v i} can save the current buffer without asking, and
@kbd{C-x v u} also operates without asking for confirmation. (This
variable does not affect @kbd{C-x v c}; that operation is so drastic
that it should always ask for confirmation.)
@kbd{C-x v u} also operates without asking for confirmation.
@vindex vc-command-messages
VC mode does much of its work by running the shell commands for the
appropriate backend. If @code{vc-command-messages} is non-@code{nil}, VC
displays messages to indicate which shell commands it runs, and
additional messages when the commands finish.
appropriate version control system. If @code{vc-command-messages} is
non-@code{nil}, VC displays messages to indicate which shell commands
it runs, and additional messages when the commands finish.
@vindex vc-path
You can specify additional directories to search for version control
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment