aa134866ad
few more memory leaks and cleaned up getopt usage. These were done shortly after the last one I imported. Very little has changed other than that. (except for some doc updates) Obtained from: cyclic.com
11658 lines
402 KiB
Plaintext
11658 lines
402 KiB
Plaintext
\input texinfo @c -*-texinfo-*-
|
||
@comment cvs.texinfo,v 1.6 1995/10/12 23:39:26 kfogel Exp
|
||
@comment Documentation for CVS.
|
||
@comment Copyright (C) 1992, 1993 Signum Support AB
|
||
@comment Copyright (C) 1993 Free Software Foundation, Inc.
|
||
|
||
@comment This file is part of the CVS distribution.
|
||
|
||
@comment CVS is free software; you can redistribute it and/or modify
|
||
@comment it under the terms of the GNU General Public License as published by
|
||
@comment the Free Software Foundation; either version 1, or (at your option)
|
||
@comment any later version.
|
||
|
||
@comment CVS is distributed in the hope that it will be useful,
|
||
@comment but WITHOUT ANY WARRANTY; without even the implied warranty of
|
||
@comment MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
|
||
@comment GNU General Public License for more details.
|
||
|
||
@c See ../README for A4 vs. US letter size.
|
||
@c When we provided A4 postscript, and people tried to
|
||
@c print it on US letter, the usual complaint was that the
|
||
@c page numbers would get cut off.
|
||
@c If one prints US letter on A4, reportedly there is
|
||
@c some extra space at the top and/or bottom, and the side
|
||
@c margins are a bit narrow, but no text is lost.
|
||
@c
|
||
@c See
|
||
@c http://www.ft.uni-erlangen.de/~mskuhn/iso-paper.html
|
||
@c for more on paper sizes. Insuring that margins are
|
||
@c big enough to print on either A4 or US letter does
|
||
@c indeed seem to be the usual approach (according to
|
||
@c an internet draft by Jacob Palme).
|
||
|
||
@c This document seems to get overfull hboxes with some
|
||
@c frequency (probably because the tendency is to
|
||
@c sanity-check it with "make info" and run TeX less
|
||
@c often). The big ugly boxes just seem to add insult
|
||
@c to injury, and I'm not aware of them helping to fix
|
||
@c the overfull hboxes at all.
|
||
@finalout
|
||
|
||
@setfilename cvs.info
|
||
@include CVSvn.texi
|
||
@settitle CVS---Concurrent Versions System
|
||
@setchapternewpage odd
|
||
|
||
@c -- TODO list:
|
||
@c -- Fix all lines that match "^@c -- "
|
||
@c -- Document how CVS finds the binaries it executes.
|
||
@c Things to include in the index:
|
||
@c Finding RCS binaries
|
||
@c Path to RCS binaries
|
||
@c RCS, how CVS finds them
|
||
@c s/RCS/diff/
|
||
@c -- More on binary files
|
||
|
||
@ifinfo
|
||
Copyright @copyright{} 1992, 1993 Signum Support AB
|
||
Copyright @copyright{} 1993, 1994 Free Software Foundation, Inc.
|
||
|
||
Permission is granted to make and distribute verbatim copies of
|
||
this manual provided the copyright notice and this permission notice
|
||
are preserved on all copies.
|
||
|
||
@ignore
|
||
Permission is granted to process this file through Tex and print the
|
||
results, provided the printed document carries copying permission
|
||
notice identical to this one except for the removal of this paragraph
|
||
(this paragraph not being relevant to the printed manual).
|
||
|
||
@end ignore
|
||
Permission is granted to copy and distribute modified versions of this
|
||
manual under the conditions for verbatim copying, provided also that the
|
||
section entitled ``GNU General Public License'' is included exactly as
|
||
in the original, and provided that the entire resulting derived work is
|
||
distributed under the terms of a permission notice identical to this one.
|
||
|
||
Permission is granted to copy and distribute translations of this manual
|
||
into another language, under the above conditions for modified versions,
|
||
except that the section entitled ``GNU General Public License'' and
|
||
this permission notice may be included in translations approved by the
|
||
Free Software Foundation instead of in the original English.
|
||
@end ifinfo
|
||
|
||
@comment The titlepage section does not appear in the Info file.
|
||
@titlepage
|
||
@sp 4
|
||
@comment The title is printed in a large font.
|
||
@center @titlefont{Version Management}
|
||
@sp
|
||
@center @titlefont{with}
|
||
@sp
|
||
@center @titlefont{CVS}
|
||
@sp 2
|
||
@center for @sc{cvs} @value{CVSVN}
|
||
@comment -release-
|
||
@sp 3
|
||
@center Per Cederqvist et al
|
||
|
||
@comment The following two commands start the copyright page
|
||
@comment for the printed manual. This will not appear in the Info file.
|
||
@page
|
||
@vskip 0pt plus 1filll
|
||
Copyright @copyright{} 1992, 1993 Signum Support AB
|
||
|
||
Permission is granted to make and distribute verbatim copies of
|
||
this manual provided the copyright notice and this permission notice
|
||
are preserved on all copies.
|
||
|
||
Permission is granted to copy and distribute modified versions of this
|
||
manual under the conditions for verbatim copying, provided also that the
|
||
section entitled ``GNU General Public License'' is included exactly as
|
||
in the original, and provided that the entire resulting derived work is
|
||
distributed under the terms of a permission notice identical to this one.
|
||
|
||
Permission is granted to copy and distribute translations of this manual
|
||
into another language, under the above conditions for modified versions,
|
||
except that the section entitled ``GNU General Public License'' and
|
||
this permission notice may be included in translations approved by the
|
||
Free Software Foundation instead of in the original English.
|
||
@end titlepage
|
||
|
||
@comment ================================================================
|
||
@comment The real text starts here
|
||
@comment ================================================================
|
||
|
||
@ifinfo
|
||
@c ---------------------------------------------------------------------
|
||
@node Top
|
||
@top
|
||
@c Note: there is a space after that @top command.
|
||
@c The texinfo-format-buffer Emacs function and
|
||
@c the makeinfo shell command disagree on what arguments
|
||
@c @top takes; @top followed by a single space is
|
||
@c something they can both cope with.
|
||
|
||
This info manual describes how to use and administer
|
||
@sc{cvs} version @value{CVSVN}.
|
||
@end ifinfo
|
||
|
||
@c This menu is pretty long. Not sure how easily that
|
||
@c can be fixed; seems like "Adding files", "Removing
|
||
@c files", "Removing directories", "Moving files",
|
||
@c and "Moving directories" all go together (into
|
||
@c "Adding, removing, and renaming"?). Other than that
|
||
@c no brilliant ideas for a fix...
|
||
@menu
|
||
* Preface:: About this manual
|
||
* What is CVS?:: What is CVS?
|
||
* A sample session:: A tour of basic CVS usage
|
||
* Repository:: Where all your sources are stored
|
||
* Starting a new project:: Starting a project with CVS
|
||
* Multiple developers:: How CVS helps a group of developers
|
||
* Revisions and branches:: Numeric, symbolic, and branch revisions
|
||
* Merging:: How to move changes between branches
|
||
* Recursive behavior:: CVS descends directories
|
||
* Adding files:: Adding files
|
||
* Removing files:: Removing files
|
||
* Removing directories:: Removing directories
|
||
* Tracking sources:: Tracking third-party sources
|
||
* Moving files:: Moving and renaming files
|
||
* Moving directories:: Moving and renaming directories
|
||
* History browsing:: Viewing the history of files in various ways
|
||
* Keyword substitution:: CVS can include the revision inside the file
|
||
* Binary files:: CVS can handle binary files
|
||
* Builds:: Issues related to CVS and builds
|
||
* Compatibility:: Upgrading CVS versions
|
||
* Revision management:: Policy questions for revision management
|
||
* CVS commands:: CVS commands share some things
|
||
* Invoking CVS:: Quick reference to CVS commands
|
||
* Administrative files:: Reference manual for the Administrative files
|
||
* Environment variables:: All environment variables which affect CVS
|
||
* Troubleshooting:: Some tips when nothing works
|
||
* Copying:: GNU GENERAL PUBLIC LICENSE
|
||
* Index:: Index
|
||
@end menu
|
||
|
||
@c ---------------------------------------------------------------------
|
||
@node Preface
|
||
@unnumbered About this manual
|
||
@cindex Preface
|
||
@cindex About this manual
|
||
|
||
Up to this point, one of the weakest parts of @sc{cvs}
|
||
has been the documentation. @sc{cvs} is a complex
|
||
program. Previous versions of the manual were written
|
||
in the manual page format, which is not really well
|
||
suited for such a complex program.
|
||
|
||
When writing this manual, I had several goals in mind:
|
||
|
||
@itemize @bullet
|
||
@item
|
||
No knowledge of @sc{rcs} should be necessary.
|
||
|
||
@item
|
||
No previous knowledge of revision control software
|
||
should be necessary. All terms, such as @dfn{revision
|
||
numbers}, @dfn{revision trees} and @dfn{merging} are
|
||
explained as they are introduced.
|
||
|
||
@item
|
||
The manual should concentrate on the things @sc{cvs} users
|
||
want to do, instead of what the @sc{cvs} commands can do.
|
||
The first part of this manual leads you through things
|
||
you might want to do while doing development, and
|
||
introduces the relevant @sc{cvs} commands as they are
|
||
needed.
|
||
|
||
@item
|
||
Information should be easy to find. In the reference
|
||
manual in the appendices almost all information about
|
||
every @sc{cvs} command is gathered together. There is also
|
||
an extensive index, and a lot of cross references.
|
||
@end itemize
|
||
|
||
@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
|
||
@menu
|
||
* Checklist::
|
||
* Credits::
|
||
* BUGS::
|
||
@end menu
|
||
|
||
@node Checklist
|
||
@unnumberedsec Checklist for the impatient reader
|
||
|
||
@sc{cvs} is a complex system. You will need to read
|
||
the manual to be able to use all of its capabilities.
|
||
There are dangers that can easily be avoided if you
|
||
know about them, and this manual tries to warn you
|
||
about them. This checklist is intended to help you
|
||
avoid the dangers without reading the entire manual.
|
||
If you intend to read the entire manual you can skip
|
||
this table.
|
||
|
||
@table @asis
|
||
@item Binary files
|
||
@sc{cvs} can handle binary files, but
|
||
you must have @sc{rcs} release 5.5 or later and
|
||
a release of @sc{gnu} diff that supports the @samp{-a}
|
||
flag (release 1.15 and later are OK). You must also
|
||
configure both @sc{rcs} and @sc{cvs} to handle binary
|
||
files when you install them.
|
||
|
||
Keyword substitution can be a source of trouble with
|
||
binary files. @xref{Keyword substitution}, for
|
||
solutions.
|
||
|
||
@item The @code{admin} command
|
||
Careless use of the @code{admin} command can cause
|
||
@sc{cvs} to cease working. @xref{admin}, before trying
|
||
to use it.
|
||
@end table
|
||
|
||
@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
|
||
@node Credits
|
||
@unnumberedsec Credits
|
||
|
||
@cindex Contributors (manual)
|
||
@cindex Credits (manual)
|
||
Roland Pesch, then of Cygnus Support <@t{roland@@wrs.com}>
|
||
wrote the manual pages which were distributed with
|
||
@sc{cvs} 1.3. Much of their text was copied into this
|
||
manual. He also read an early draft
|
||
of this manual and contributed many ideas and
|
||
corrections.
|
||
|
||
The mailing-list @code{info-cvs} is sometimes
|
||
informative. I have included information from postings
|
||
made by the following persons:
|
||
David G. Grubbs <@t{dgg@@think.com}>.
|
||
|
||
Some text has been extracted from the man pages for
|
||
@sc{rcs}.
|
||
|
||
The @sc{cvs} @sc{faq} by David G. Grubbs has provided
|
||
useful material. The @sc{faq} is no longer maintained,
|
||
however, and this manual is about the closest thing there
|
||
is to a successor (with respect to documenting how to
|
||
use @sc{cvs}, at least).
|
||
|
||
In addition, the following persons have helped by
|
||
telling me about mistakes I've made:
|
||
|
||
@display
|
||
Roxanne Brunskill <@t{rbrunski@@datap.ca}>,
|
||
Kathy Dyer <@t{dyer@@phoenix.ocf.llnl.gov}>,
|
||
Karl Pingle <@t{pingle@@acuson.com}>,
|
||
Thomas A Peterson <@t{tap@@src.honeywell.com}>,
|
||
Inge Wallin <@t{ingwa@@signum.se}>,
|
||
Dirk Koschuetzki <@t{koschuet@@fmi.uni-passau.de}>
|
||
and Michael Brown <@t{brown@@wi.extrel.com}>.
|
||
@end display
|
||
|
||
The list of contributors here is not comprehensive; for a more
|
||
complete list of who has contributed to this manual see
|
||
the file @file{doc/ChangeLog} in the @sc{cvs} source
|
||
distribution.
|
||
|
||
@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
|
||
@node BUGS
|
||
@unnumberedsec BUGS
|
||
|
||
@cindex Bugs in this manual or CVS
|
||
Neither @sc{cvs} nor this manual is perfect, and they
|
||
probably never will be. If you are having trouble
|
||
using @sc{cvs}, or think you have found a bug, there
|
||
are a number of things you can do about it. Note that
|
||
if the manual is unclear, that can be considered a bug
|
||
in the manual, so these problems are often worth doing
|
||
something about as well as problems with @sc{cvs} itself.
|
||
|
||
@cindex Reporting bugs
|
||
@cindex Bugs, reporting
|
||
@cindex Errors, reporting
|
||
@itemize @bullet
|
||
@item
|
||
If you want someone to help you and fix bugs that you
|
||
report, there are companies which will do that for a
|
||
fee. Two such companies are:
|
||
|
||
@cindex Signum Support
|
||
@cindex Cyclic Software
|
||
@cindex Support, getting CVS support
|
||
@example
|
||
Signum Support AB
|
||
Box 2044
|
||
S-580 02 Linkoping
|
||
Sweden
|
||
Email: info@@signum.se
|
||
Phone: +46 (0)13 - 21 46 00
|
||
Fax: +46 (0)13 - 21 47 00
|
||
http://www.signum.se/
|
||
|
||
Cyclic Software
|
||
United States of America
|
||
http://www.cyclic.com/
|
||
info@@cyclic.com
|
||
@end example
|
||
|
||
@item
|
||
If you got @sc{cvs} through a distributor, such as an
|
||
operating system vendor or a vendor of freeware
|
||
@sc{cd-rom}s, you may wish to see whether the
|
||
distributor provides support. Often, they will provide
|
||
no support or minimal support, but this may vary from
|
||
distributor to distributor.
|
||
|
||
@item
|
||
If you have the skills and time to do so, you may wish
|
||
to fix the bug yourself. If you wish to submit your
|
||
fix for inclusion in future releases of @sc{cvs}, see
|
||
the file @sc{hacking} in the @sc{cvs} source
|
||
distribution. It contains much more information on the
|
||
process of submitting fixes.
|
||
|
||
@item
|
||
There may be resources on the net which can help. Two
|
||
good places to start are:
|
||
|
||
@example
|
||
http://www.cyclic.com
|
||
@r{particularly the Unsupported Resources page}
|
||
http://www.loria.fr/~molli/cvs-index.html
|
||
@end example
|
||
|
||
If you are so inspired, increasing the information
|
||
available on the net is likely to be appreciated. For
|
||
example, before the standard @sc{cvs} distribution
|
||
worked on Windows 95, there was a web page with some
|
||
explanation and patches for running @sc{cvs} on Windows
|
||
95, and various people helped out by mentioning this
|
||
page on mailing lists or newsgroups when the subject
|
||
came up.
|
||
|
||
@item
|
||
It is also possible to report bugs to @code{bug-cvs}.
|
||
Note that someone may or may not want to do anything
|
||
with your bug report---if you need a solution consider
|
||
one of the options mentioned above. People probably do
|
||
want to hear about bugs which are particularly severe
|
||
in consequences and/or easy to fix, however. You can
|
||
also increase your odds by being as clear as possible
|
||
about the exact nature of the bug and any other
|
||
relevant information. The way to report bugs is to
|
||
send email to @code{bug-cvs@@prep.ai.mit.edu}. Note
|
||
that submissions to @code{bug-cvs} may be distributed
|
||
under the terms of the @sc{gnu} Public License, so if
|
||
you don't like this, don't submit them. There is
|
||
usually no justification for sending mail directly to
|
||
one of the @sc{cvs} maintainers rather than to
|
||
@code{bug-cvs}; those maintainers who want to hear
|
||
about such bug reports read @code{bug-cvs}. Also note
|
||
that sending a bug report to other mailing lists or
|
||
newsgroups is @emph{not} a substitute for sending it to
|
||
@code{bug-cvs}. It is fine to discuss @sc{cvs} bugs on
|
||
whatever forum you prefer, but there are not
|
||
necessarily any maintainers reading bug reports sent
|
||
anywhere except @code{bug-cvs}.
|
||
@end itemize
|
||
|
||
@cindex Known bugs in this manual or CVS
|
||
People often ask if there is a list of known bugs or
|
||
whether a particular bug is a known one. The file
|
||
@sc{bugs} in the @sc{cvs} source distribution is one
|
||
list of known bugs, but it doesn't necessarily try to
|
||
be comprehensive. Perhaps there will never be a
|
||
comprehensive, detailed list of known bugs.
|
||
|
||
@c ---------------------------------------------------------------------
|
||
@node What is CVS?
|
||
@chapter What is CVS?
|
||
@cindex What is CVS?
|
||
@cindex Introduction to CVS
|
||
@cindex CVS, introduction to
|
||
|
||
@sc{cvs} is a version control system. Using it, you can
|
||
record the history of your source files.
|
||
|
||
@c -- ///
|
||
@c -- ///Those who cannot remember the past are condemned to repeat it.
|
||
@c -- /// -- George Santayana
|
||
@c -- //////
|
||
|
||
@c -- Insert history quote here!
|
||
For example, bugs sometimes creep in when
|
||
software is modified, and you might not detect the bug
|
||
until a long time after you make the modification.
|
||
With @sc{cvs}, you can easily retrieve old versions to see
|
||
exactly which change caused the bug. This can
|
||
sometimes be a big help.
|
||
|
||
You could of course save every version of every file
|
||
you have ever created. This would
|
||
however waste an enormous amount of disk space. @sc{cvs}
|
||
stores all the versions of a file in a single file in a
|
||
clever way that only stores the differences between
|
||
versions.
|
||
|
||
@sc{cvs} also helps you if you are part of a group of people working
|
||
on the same project. It is all too easy to overwrite
|
||
each others' changes unless you are extremely careful.
|
||
Some editors, like @sc{gnu} Emacs, try to make sure that
|
||
the same file is never modified by two people at the
|
||
same time. Unfortunately, if someone is using another
|
||
editor, that safeguard will not work. @sc{cvs} solves this problem
|
||
by insulating the different developers from each other. Every
|
||
developer works in his own directory, and @sc{cvs} merges
|
||
the work when each developer is done.
|
||
|
||
@cindex History of CVS
|
||
@cindex CVS, history of
|
||
@cindex Credits (CVS program)
|
||
@cindex Contributors (CVS program)
|
||
@sc{cvs} started out as a bunch of shell scripts written by
|
||
Dick Grune, posted to the newsgroup
|
||
@code{comp.sources.unix} in the volume 6
|
||
release of December, 1986. While no actual code from
|
||
these shell scripts is present in the current version
|
||
of @sc{cvs} much of the @sc{cvs} conflict resolution algorithms
|
||
come from them.
|
||
|
||
In April, 1989, Brian Berliner designed and coded @sc{cvs}.
|
||
Jeff Polk later helped Brian with the design of the @sc{cvs}
|
||
module and vendor branch support.
|
||
|
||
@cindex Source, getting CVS source
|
||
You can get @sc{cvs} via anonymous @sc{ftp} from a
|
||
number of sites; for example see
|
||
@example
|
||
http://www.gnu.ai.mit.edu/order/ftp.html
|
||
@end example
|
||
for a list of the @sc{gnu} @sc{ftp} sites.
|
||
@c We could also be pointing to other resources like
|
||
@c the cyclic getting.html, Pascal Molli's page, etc.,
|
||
@c and probably should, when someone gets around to
|
||
@c figuring out which pages are stable enough that we
|
||
@c should cite them, which ones are best to point
|
||
@c people to (supported? binary? source? zero-cost?
|
||
@c buying CD-ROMs? etc.), etc.
|
||
|
||
@cindex Mailing list
|
||
@cindex List, mailing list
|
||
@cindex Newsgroups
|
||
@c Be careful in editing this--it is worded so that
|
||
@c the long -request address is in the middle of a
|
||
@c line, thus avoiding overfull hboxes.
|
||
There is a mailing list, known as @w{@code{info-cvs}},
|
||
devoted to @sc{cvs}. To subscribe or
|
||
unsubscribe
|
||
@c could add "to the mailing list,"
|
||
send a message to
|
||
@c or "write to"
|
||
@w{@code{info-cvs-request@@prep.ai.mit.edu}}. Please
|
||
be specific about your email address. As of May 1996,
|
||
subscription requests are handled by a busy human
|
||
being, so you cannot expect to be added or removed
|
||
immediately. If you prefer a usenet group, the right
|
||
group is @code{comp.software.config-mgmt} which is for
|
||
@sc{cvs} discussions (along with other configuration
|
||
management systems). In the future, it might be
|
||
possible to create a
|
||
@code{comp.software.config-mgmt.cvs}, but probably only
|
||
if there is sufficient @sc{cvs} traffic on
|
||
@code{comp.software.config-mgmt}.
|
||
@c Other random data is that past attempts to create a
|
||
@c gnu.* group have failed (the relevant authorities
|
||
@c say they'll do it, but don't), and that tale was very
|
||
@c skeptical of comp.software.config-mgmt.cvs when the
|
||
@c subject came up around 1995 or so (for one
|
||
@c thing, because creating it would be a "reorg" which
|
||
@c would need to take a more comprehensive look at the
|
||
@c whole comp.software.config-mgmt.* hierarchy).
|
||
|
||
You can also subscribe to the bug-cvs mailing list,
|
||
described in more detail in @ref{BUGS}. To subscribe
|
||
send mail to bug-cvs-request@@prep.ai.mit.edu.
|
||
|
||
@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
|
||
@unnumberedsec CVS is not@dots{}
|
||
|
||
@sc{cvs} can do a lot of things for you, but it does
|
||
not try to be everything for everyone.
|
||
|
||
@table @asis
|
||
@item @sc{cvs} is not a build system.
|
||
|
||
Though the structure of your repository and modules
|
||
file interact with your build system
|
||
(e.g. @file{Makefile}s), they are essentially
|
||
independent.
|
||
|
||
@sc{cvs} does not dictate how you build anything. It
|
||
merely stores files for retrieval in a tree structure
|
||
you devise.
|
||
|
||
@sc{cvs} does not dictate how to use disk space in the
|
||
checked out working directories. If you write your
|
||
@file{Makefile}s or scripts in every directory so they
|
||
have to know the relative positions of everything else,
|
||
you wind up requiring the entire repository to be
|
||
checked out.
|
||
|
||
If you modularize your work, and construct a build
|
||
system that will share files (via links, mounts,
|
||
@code{VPATH} in @file{Makefile}s, etc.), you can
|
||
arrange your disk usage however you like.
|
||
|
||
But you have to remember that @emph{any} such system is
|
||
a lot of work to construct and maintain. @sc{cvs} does
|
||
not address the issues involved.
|
||
|
||
Of course, you should place the tools created to
|
||
support such a build system (scripts, @file{Makefile}s,
|
||
etc) under @sc{cvs}.
|
||
|
||
Figuring out what files need to be rebuilt when
|
||
something changes is, again, something to be handled
|
||
outside the scope of @sc{cvs}. One traditional
|
||
approach is to use @code{make} for building, and use
|
||
some automated tool for generating the dependencies which
|
||
@code{make} uses.
|
||
|
||
See @ref{Builds}, for more information on doing builds
|
||
in conjunction with @sc{cvs}.
|
||
|
||
@item @sc{cvs} is not a substitute for management.
|
||
|
||
Your managers and project leaders are expected to talk
|
||
to you frequently enough to make certain you are aware
|
||
of schedules, merge points, branch names and release
|
||
dates. If they don't, @sc{cvs} can't help.
|
||
|
||
@sc{cvs} is an instrument for making sources dance to
|
||
your tune. But you are the piper and the composer. No
|
||
instrument plays itself or writes its own music.
|
||
|
||
@item @sc{cvs} is not a substitute for developer communication.
|
||
|
||
When faced with conflicts within a single file, most
|
||
developers manage to resolve them without too much
|
||
effort. But a more general definition of ``conflict''
|
||
includes problems too difficult to solve without
|
||
communication between developers.
|
||
|
||
@sc{cvs} cannot determine when simultaneous changes
|
||
within a single file, or across a whole collection of
|
||
files, will logically conflict with one another. Its
|
||
concept of a @dfn{conflict} is purely textual, arising
|
||
when two changes to the same base file are near enough
|
||
to spook the merge (i.e. @code{diff3}) command.
|
||
|
||
@sc{cvs} does not claim to help at all in figuring out
|
||
non-textual or distributed conflicts in program logic.
|
||
|
||
For example: Say you change the arguments to function
|
||
@code{X} defined in file @file{A}. At the same time,
|
||
someone edits file @file{B}, adding new calls to
|
||
function @code{X} using the old arguments. You are
|
||
outside the realm of @sc{cvs}'s competence.
|
||
|
||
Acquire the habit of reading specs and talking to your
|
||
peers.
|
||
|
||
|
||
@item @sc{cvs} does not have change control
|
||
|
||
Change control refers to a number of things. First of
|
||
all it can mean @dfn{bug-tracking}, that is being able
|
||
to keep a database of reported bugs and the status of
|
||
each one (is it fixed? in what release? has the bug
|
||
submitter agreed that it is fixed?). For interfacing
|
||
@sc{cvs} to an external bug-tracking system, see the
|
||
@file{rcsinfo} and @file{verifymsg} files
|
||
(@pxref{Administrative files}).
|
||
|
||
Another aspect of change control is keeping track of
|
||
the fact that changes to several files were in fact
|
||
changed together as one logical change. If you check
|
||
in several files in a single @code{cvs commit}
|
||
operation, @sc{cvs} then forgets that those files were
|
||
checked in together, and the fact that they have the
|
||
same log message is the only thing tying them
|
||
together. Keeping a @sc{gnu} style @file{ChangeLog}
|
||
can help somewhat.
|
||
@c FIXME: should have an xref to a section which talks
|
||
@c more about keeping ChangeLog's with CVS, but that
|
||
@c section hasn't been written yet.
|
||
|
||
Another aspect of change control, in some systems, is
|
||
the ability to keep track of the status of each
|
||
change. Some changes have been written by a developer,
|
||
others have been reviewed by a second developer, and so
|
||
on. Generally, the way to do this with @sc{cvs} is to
|
||
generate a diff (using @code{cvs diff} or @code{diff})
|
||
and email it to someone who can then apply it using the
|
||
@code{patch} utility. This is very flexible, but
|
||
depends on mechanisms outside @sc{cvs} to make sure
|
||
nothing falls through the cracks.
|
||
|
||
@item @sc{cvs} is not an automated testing program
|
||
|
||
It should be possible to enforce mandatory use of a
|
||
testsuite using the @code{commitinfo} file. I haven't
|
||
heard a lot about projects trying to do that or whether
|
||
there are subtle gotchas, however.
|
||
|
||
@item @sc{cvs} does not have a builtin process model
|
||
|
||
Some systems provide ways to ensure that changes or
|
||
releases go through various steps, with various
|
||
approvals as needed. Generally, one can accomplish
|
||
this with @sc{cvs} but it might be a little more work.
|
||
In some cases you'll want to use the @file{commitinfo},
|
||
@file{loginfo}, @file{rcsinfo}, or @file{verifymsg}
|
||
files, to require that certain steps be performed
|
||
before cvs will allow a checkin. Also consider whether
|
||
features such as branches and tags can be used to
|
||
perform tasks such as doing work in a development tree
|
||
and then merging certain changes over to a stable tree
|
||
only once they have been proven.
|
||
@end table
|
||
|
||
@c ---------------------------------------------------------------------
|
||
@node A sample session
|
||
@chapter A sample session
|
||
@cindex A sample session
|
||
@cindex Example of a work-session
|
||
@cindex Getting started
|
||
@cindex Work-session, example of
|
||
@cindex tc, Trivial Compiler (example)
|
||
@cindex Trivial Compiler (example)
|
||
|
||
@c I think an example is a pretty good way to start. But
|
||
@c somewhere in here, maybe after the sample session,
|
||
@c we need something which is kind of
|
||
@c a "roadmap" which is more directed at sketching out
|
||
@c the functionality of CVS and pointing people to
|
||
@c various other parts of the manual. As it stands now
|
||
@c people who read in order get dumped right into all
|
||
@c manner of hair regarding remote repositories,
|
||
@c creating a repository, etc.
|
||
@c
|
||
@c The following was in the old Basic concepts node. I don't
|
||
@c know how good a job it does at introducing modules,
|
||
@c or whether they need to be introduced so soon, but
|
||
@c something of this sort might go into some
|
||
@c introductory material somewhere.
|
||
@ignore
|
||
@cindex Modules (intro)
|
||
The repository contains directories and files, in an
|
||
arbitrary tree. The @dfn{modules} feature can be used
|
||
to group together a set of directories or files into a
|
||
single entity (@pxref{modules}). A typical usage is to
|
||
define one module per project.
|
||
@end ignore
|
||
|
||
As a way of introducing @sc{cvs}, we'll go through a
|
||
typical work-session using @sc{cvs}. The first thing
|
||
to understand is that @sc{cvs} stores all files in a
|
||
centralized @dfn{repository} (@pxref{Repository}); this
|
||
section assumes that a repository is set up.
|
||
@c I'm not sure that the sentence concerning the
|
||
@c repository quite tells the user what they need to
|
||
@c know at this point. Might need to expand on "centralized"
|
||
@c slightly (maybe not here, maybe further down in the example?)
|
||
|
||
Suppose you are working on a simple compiler. The source
|
||
consists of a handful of C files and a @file{Makefile}.
|
||
The compiler is called @samp{tc} (Trivial Compiler),
|
||
and the repository is set up so that there is a module
|
||
called @samp{tc}.
|
||
|
||
@menu
|
||
* Getting the source:: Creating a workspace
|
||
* Committing your changes:: Making your work available to others
|
||
* Cleaning up:: Cleaning up
|
||
* Viewing differences:: Viewing differences
|
||
@end menu
|
||
|
||
@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
|
||
@node Getting the source
|
||
@section Getting the source
|
||
@cindex Getting the source
|
||
@cindex Checking out source
|
||
@cindex Fetching source
|
||
@cindex Source, getting from CVS
|
||
@cindex Checkout, example
|
||
|
||
The first thing you must do is to get your own working copy of the
|
||
source for @samp{tc}. For this, you use the @code{checkout} command:
|
||
|
||
@example
|
||
$ cvs checkout tc
|
||
@end example
|
||
|
||
@noindent
|
||
This will create a new directory called @file{tc} and populate it with
|
||
the source files.
|
||
|
||
@example
|
||
$ cd tc
|
||
$ ls
|
||
CVS Makefile backend.c driver.c frontend.c parser.c
|
||
@end example
|
||
|
||
The @file{CVS} directory is used internally by
|
||
@sc{cvs}. Normally, you should not modify or remove
|
||
any of the files in it.
|
||
|
||
You start your favorite editor, hack away at @file{backend.c}, and a couple
|
||
of hours later you have added an optimization pass to the compiler.
|
||
A note to @sc{rcs} and @sc{sccs} users: There is no need to lock the files that
|
||
you want to edit. @xref{Multiple developers}, for an explanation.
|
||
|
||
@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
|
||
@node Committing your changes
|
||
@section Committing your changes
|
||
@cindex Committing changes
|
||
@cindex Log message entry
|
||
@cindex CVSEDITOR, environment variable
|
||
@cindex EDITOR, environment variable
|
||
|
||
When you have checked that the compiler is still compilable you decide
|
||
to make a new version of @file{backend.c}. This will
|
||
store your new @file{backend.c} in the repository and
|
||
make it available to anyone else who is using that same
|
||
repository.
|
||
|
||
@example
|
||
$ cvs commit backend.c
|
||
@end example
|
||
|
||
@noindent
|
||
@sc{cvs} starts an editor, to allow you to enter a log
|
||
message. You type in ``Added an optimization pass.'',
|
||
save the temporary file, and exit the editor.
|
||
|
||
The environment variable @code{$CVSEDITOR} determines
|
||
which editor is started. If @code{$CVSEDITOR} is not
|
||
set, then if the environment variable @code{$EDITOR} is
|
||
set, it will be used. If both @code{$CVSEDITOR} and
|
||
@code{$EDITOR} are not set then there is a default
|
||
which will vary with your operating system, for example
|
||
@code{vi} for unix or @code{notepad} for Windows
|
||
NT/95.
|
||
|
||
@c This probably should go into some new node
|
||
@c containing detailed info on the editor, rather than
|
||
@c the intro. In fact, perhaps some of the stuff with
|
||
@c CVSEDITOR and -m and so on should too.
|
||
When @sc{cvs} starts the editor, it includes a list of
|
||
files which are modified. For the @sc{cvs} client,
|
||
this list is based on comparing the modification time
|
||
of the file against the modification time that the file
|
||
had when it was last gotten or updated. Therefore, if
|
||
a file's modification time has changed but its contents
|
||
have not, it will show up as modified. The simplest
|
||
way to handle this is simply not to worry about it---if
|
||
you proceed with the commit @sc{cvs} will detect that
|
||
the contents are not modified and treat it as an
|
||
unmodified file. The next @code{update} will clue
|
||
@sc{cvs} in to the fact that the file is unmodified,
|
||
and it will reset its stored timestamp so that the file
|
||
will not show up in future editor sessions.
|
||
@c FIXCVS: Might be nice if "commit" and other commands
|
||
@c would reset that timestamp too, but currently commit
|
||
@c doesn't.
|
||
|
||
If you want to avoid
|
||
starting an editor you can specify the log message on
|
||
the command line using the @samp{-m} flag instead, like
|
||
this:
|
||
|
||
@example
|
||
$ cvs commit -m "Added an optimization pass" backend.c
|
||
@end example
|
||
|
||
@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
|
||
@node Cleaning up
|
||
@section Cleaning up
|
||
@cindex Cleaning up
|
||
@cindex Working copy, removing
|
||
@cindex Removing your working copy
|
||
@cindex Releasing your working copy
|
||
|
||
Before you turn to other tasks you decide to remove your working copy of
|
||
tc. One acceptable way to do that is of course
|
||
|
||
@example
|
||
$ cd ..
|
||
$ rm -r tc
|
||
@end example
|
||
|
||
@noindent
|
||
but a better way is to use the @code{release} command (@pxref{release}):
|
||
|
||
@example
|
||
$ cd ..
|
||
$ cvs release -d tc
|
||
M driver.c
|
||
? tc
|
||
You have [1] altered files in this repository.
|
||
Are you sure you want to release (and delete) module `tc': n
|
||
** `release' aborted by user choice.
|
||
@end example
|
||
|
||
The @code{release} command checks that all your modifications have been
|
||
committed. If history logging is enabled it also makes a note in the
|
||
history file. @xref{history file}.
|
||
|
||
When you use the @samp{-d} flag with @code{release}, it
|
||
also removes your working copy.
|
||
|
||
In the example above, the @code{release} command wrote a couple of lines
|
||
of output. @samp{? tc} means that the file @file{tc} is unknown to @sc{cvs}.
|
||
That is nothing to worry about: @file{tc} is the executable compiler,
|
||
and it should not be stored in the repository. @xref{cvsignore},
|
||
for information about how to make that warning go away.
|
||
@xref{release output}, for a complete explanation of
|
||
all possible output from @code{release}.
|
||
|
||
@samp{M driver.c} is more serious. It means that the
|
||
file @file{driver.c} has been modified since it was
|
||
checked out.
|
||
|
||
The @code{release} command always finishes by telling
|
||
you how many modified files you have in your working
|
||
copy of the sources, and then asks you for confirmation
|
||
before deleting any files or making any note in the
|
||
history file.
|
||
|
||
You decide to play it safe and answer @kbd{n @key{RET}}
|
||
when @code{release} asks for confirmation.
|
||
|
||
@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
|
||
@node Viewing differences
|
||
@section Viewing differences
|
||
@cindex Viewing differences
|
||
@cindex Diff
|
||
|
||
You do not remember modifying @file{driver.c}, so you want to see what
|
||
has happened to that file.
|
||
|
||
@example
|
||
$ cd tc
|
||
$ cvs diff driver.c
|
||
@end example
|
||
|
||
This command runs @code{diff} to compare the version of @file{driver.c}
|
||
that you checked out with your working copy. When you see the output
|
||
you remember that you added a command line option that enabled the
|
||
optimization pass. You check it in, and release the module.
|
||
@c FIXME: we haven't yet defined the term "check in".
|
||
|
||
@example
|
||
$ cvs commit -m "Added an optimization pass" driver.c
|
||
Checking in driver.c;
|
||
/usr/local/cvsroot/tc/driver.c,v <-- driver.c
|
||
new revision: 1.2; previous revision: 1.1
|
||
done
|
||
$ cd ..
|
||
$ cvs release -d tc
|
||
? tc
|
||
You have [0] altered files in this repository.
|
||
Are you sure you want to release (and delete) module `tc': y
|
||
@end example
|
||
|
||
@c ---------------------------------------------------------------------
|
||
@node Repository
|
||
@chapter The Repository
|
||
@cindex Repository (intro)
|
||
@cindex Repository, example
|
||
@cindex Layout of repository
|
||
@cindex Typical repository
|
||
@cindex /usr/local/cvsroot, as example repository
|
||
@cindex cvsroot
|
||
|
||
The @sc{cvs} @dfn{repository} stores a complete copy of
|
||
all the files and directories which are under version
|
||
control.
|
||
|
||
Normally, you never access any of the files in the
|
||
repository directly. Instead, you use @sc{cvs}
|
||
commands to get your own copy of the files into a
|
||
@dfn{working directory}, and then
|
||
work on that copy. When you've finished a set of
|
||
changes, you check (or @dfn{commit}) them back into the
|
||
repository. The repository then contains the changes
|
||
which you have made, as well as recording exactly what
|
||
you changed, when you changed it, and other such
|
||
information. Note that the repository is not a
|
||
subdirectory of the working directory, or vice versa;
|
||
they should be in separate locations.
|
||
@c Need some example, e.g. repository
|
||
@c /usr/local/cvsroot; working directory
|
||
@c /home/joe/sources. But this node is too long
|
||
@c as it is; need a little reorganization...
|
||
|
||
@cindex :local:
|
||
@sc{Cvs} can access a repository by a variety of
|
||
means. It might be on the local computer, or it might
|
||
be on a computer across the room or across the world.
|
||
To distinguish various ways to access a repository, the
|
||
repository name can start with an @dfn{access method}.
|
||
For example, the access method @code{:local:} means to
|
||
access a repository directory, so the repository
|
||
@code{:local:/usr/local/cvsroot} means that the
|
||
repository is in @file{/usr/local/cvsroot} on the
|
||
computer running @sc{cvs}. For information on other
|
||
access methods, see @ref{Remote repositories}.
|
||
|
||
@c Can se say this more concisely? Like by passing
|
||
@c more of the buck to the Remote repositories node?
|
||
If the access method is omitted, then if the repository
|
||
does not contain @samp{:}, then @code{:local:} is
|
||
assumed. If it does contain @samp{:} than either
|
||
@code{:ext:} or @code{:server:} is assumed. For
|
||
example, if you have a local repository in
|
||
@file{/usr/local/cvsroot}, you can use
|
||
@code{/usr/local/cvsroot} instead of
|
||
@code{:local:/usr/local/cvsroot}. But if (under
|
||
Windows NT, for example) your local repository is
|
||
@file{c:\src\cvsroot}, then you must specify the access
|
||
method, as in @code{:local:c:\src\cvsroot}.
|
||
|
||
@c This might appear to go in Repository storage, but
|
||
@c actually it is describing something which is quite
|
||
@c user-visible, when you do a "cvs co CVSROOT". This
|
||
@c isn't necessary the perfect place for that, though.
|
||
The repository is split in two parts. @file{$CVSROOT/CVSROOT} contains
|
||
administrative files for @sc{cvs}. The other directories contain the actual
|
||
user-defined modules.
|
||
|
||
@menu
|
||
* Specifying a repository:: Telling CVS where your repository is
|
||
* Repository storage:: The structure of the repository
|
||
* Working directory storage:: The structure of working directories
|
||
* Intro administrative files:: Defining modules
|
||
* Multiple repositories:: Multiple repositories
|
||
* Creating a repository:: Creating a repository
|
||
* Backing up:: Backing up a repository
|
||
* Remote repositories:: Accessing repositories on remote machines
|
||
* Read-only access:: Granting read-only access to the repository
|
||
* Server temporary directory:: The server creates temporary directories
|
||
@end menu
|
||
|
||
@node Specifying a repository
|
||
@section Telling CVS where your repository is
|
||
|
||
There are a couple of different ways to tell @sc{cvs}
|
||
where to find the repository. You can name the
|
||
repository on the command line explicitly, with the
|
||
@code{-d} (for "directory") option:
|
||
|
||
@example
|
||
cvs -d /usr/local/cvsroot checkout yoyodyne/tc
|
||
@end example
|
||
|
||
@cindex .profile, setting CVSROOT in
|
||
@cindex .cshrc, setting CVSROOT in
|
||
@cindex .tcshrc, setting CVSROOT in
|
||
@cindex .bashrc, setting CVSROOT in
|
||
@cindex CVSROOT, environment variable
|
||
Or you can set the @code{$CVSROOT} environment
|
||
variable to an absolute path to the root of the
|
||
repository, @file{/usr/local/cvsroot} in this example.
|
||
To set @code{$CVSROOT}, all @code{csh} and @code{tcsh}
|
||
users should have this line in their @file{.cshrc} or
|
||
@file{.tcshrc} files:
|
||
|
||
@example
|
||
setenv CVSROOT /usr/local/cvsroot
|
||
@end example
|
||
|
||
@noindent
|
||
@code{sh} and @code{bash} users should instead have these lines in their
|
||
@file{.profile} or @file{.bashrc}:
|
||
|
||
@example
|
||
CVSROOT=/usr/local/cvsroot
|
||
export CVSROOT
|
||
@end example
|
||
|
||
@cindex Root file, in CVS directory
|
||
@cindex CVS/Root file
|
||
A repository specified with @code{-d} will
|
||
override the @code{$CVSROOT} environment variable.
|
||
Once you've checked a working copy out from the
|
||
repository, it will remember where its repository is
|
||
(the information is recorded in the
|
||
@file{CVS/Root} file in the working copy).
|
||
|
||
The @code{-d} option and the @file{CVS/Root} file both
|
||
override the @code{$CVSROOT} environment variable. If
|
||
@code{-d} option differs from @file{CVS/Root}, the
|
||
former is used (and specifying @code{-d} will cause
|
||
@file{CVS/Root} to be updated). Of course, for proper
|
||
operation they should be two ways of referring to the
|
||
same repository.
|
||
|
||
@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
|
||
@node Repository storage
|
||
@section How data is stored in the repository
|
||
@cindex Repository, how data is stored
|
||
|
||
For most purposes it isn't important @emph{how}
|
||
@sc{cvs} stores information in the repository. In
|
||
fact, the format has changed in the past, and is likely
|
||
to change in the future. Since in almost all cases one
|
||
accesses the repository via @sc{cvs} commands; such
|
||
changes need not be disruptive.
|
||
|
||
However, in some cases it may be necessary to
|
||
understand how @sc{cvs} stores data in the repository,
|
||
for example you might need to track down @sc{cvs} locks
|
||
(@pxref{Concurrency}) or you might need to deal with
|
||
the file permissions appropriate for the repository.
|
||
|
||
@menu
|
||
* Repository files:: What files are stored in the repository
|
||
* File permissions:: File permissions
|
||
* Attic:: Some files are stored in the Attic
|
||
@end menu
|
||
|
||
@node Repository files
|
||
@subsection Where files are stored within the repository
|
||
|
||
The overall structure of the repository is a directory
|
||
tree corresponding to the directories in the working
|
||
directory. For example, supposing the repository is in
|
||
|
||
@example
|
||
/usr/local/cvsroot
|
||
@end example
|
||
|
||
@noindent
|
||
here is a possible directory tree (showing only the
|
||
directories):
|
||
|
||
@example
|
||
@t{/usr}
|
||
|
|
||
+--@t{local}
|
||
| |
|
||
| +--@t{cvsroot}
|
||
| | |
|
||
| | +--@t{CVSROOT}
|
||
| (administrative files)
|
||
|
|
||
+--@t{gnu}
|
||
| |
|
||
| +--@t{diff}
|
||
| | (source code to @sc{gnu} diff)
|
||
| |
|
||
| +--@t{rcs}
|
||
| | (source code to @sc{rcs})
|
||
| |
|
||
| +--@t{cvs}
|
||
| (source code to @sc{cvs})
|
||
|
|
||
+--@t{yoyodyne}
|
||
|
|
||
+--@t{tc}
|
||
| |
|
||
| +--@t{man}
|
||
| |
|
||
| +--@t{testing}
|
||
|
|
||
+--(other Yoyodyne software)
|
||
@end example
|
||
|
||
With the directories are @dfn{history files} for each file
|
||
under version control. The name of the history file is
|
||
the name of the corresponding file with @samp{,v}
|
||
appended to the end. Here is what the repository for
|
||
the @file{yoyodyne/tc} directory might look like:
|
||
@c FIXME: Should also mention CVS (CVSREP)
|
||
@c FIXME? Should we introduce Attic with an xref to
|
||
@c Attic? Not sure whether that is a good idea or not.
|
||
@example
|
||
@code{$CVSROOT}
|
||
|
|
||
+--@t{yoyodyne}
|
||
| |
|
||
| +--@t{tc}
|
||
| | |
|
||
+--@t{Makefile,v}
|
||
+--@t{backend.c,v}
|
||
+--@t{driver.c,v}
|
||
+--@t{frontend.c,v}
|
||
+--@t{parser.c,v}
|
||
+--@t{man}
|
||
| |
|
||
| +--@t{tc.1,v}
|
||
|
|
||
+--@t{testing}
|
||
|
|
||
+--@t{testpgm.t,v}
|
||
+--@t{test2.t,v}
|
||
@end example
|
||
|
||
@cindex History files
|
||
@cindex RCS history files
|
||
@c The first sentence, about what history files
|
||
@c contain, is kind of redundant with our intro to what the
|
||
@c repository does in node Repository....
|
||
The history files contain, among other things, enough
|
||
information to recreate any revision of the file, a log
|
||
of all commit messages and the user-name of the person
|
||
who committed the revision. The history files are
|
||
known as @dfn{RCS files}, because the first program to
|
||
store files in that format was a version control system
|
||
known as @sc{rcs}. For a full
|
||
description of the file format, see the @code{man} page
|
||
@cite{rcsfile(5)}, distributed with @sc{rcs}. This
|
||
file format has become very common---many systems other
|
||
than @sc{cvs} or @sc{rcs} can at least import history
|
||
files in this format.
|
||
@c FIXME: Think about including documentation for this
|
||
@c rather than citing it? In the long run, getting
|
||
@c this to be a standard (not sure if we can cope with
|
||
@c a standards process as formal as IEEE/ANSI/ISO/etc,
|
||
@c though...) is the way to go, so maybe citing is
|
||
@c better.
|
||
|
||
The @sc{rcs} files used in @sc{cvs} differ in a few
|
||
ways from the standard format. The biggest difference
|
||
is magic branches; for more information see @ref{Magic
|
||
branch numbers}. Also in @sc{cvs} the valid tag names
|
||
are a subset of what @sc{rcs} accepts; for @sc{cvs}'s
|
||
rules see @ref{Tags}.
|
||
|
||
@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
|
||
@node File permissions
|
||
@subsection File permissions
|
||
@c -- Move this to @node Creating a repository or similar
|
||
@cindex Security
|
||
@cindex File permissions
|
||
@cindex Group
|
||
@cindex read-only files, in repository
|
||
All @samp{,v} files are created read-only, and you
|
||
should not change the permission of those files. The
|
||
directories inside the repository should be writable by
|
||
the persons that have permission to modify the files in
|
||
each directory. This normally means that you must
|
||
create a UNIX group (see group(5)) consisting of the
|
||
persons that are to edit the files in a project, and
|
||
set up the repository so that it is that group that
|
||
owns the directory.
|
||
@c See also comment in commitinfo node regarding cases
|
||
@c which are really awkward with unix groups.
|
||
|
||
This means that you can only control access to files on
|
||
a per-directory basis.
|
||
|
||
Note that users must also have write access to check
|
||
out files, because @sc{cvs} needs to create lock files
|
||
(@pxref{Concurrency}).
|
||
|
||
@c CVS seems to use CVSUMASK in picking permissions for
|
||
@c val-tags, but maybe we should say more about this.
|
||
@c Like val-tags gets created by someone who doesn't
|
||
@c have CVSUMASK set right?
|
||
Also note that users must have write access to the
|
||
@file{CVSROOT/val-tags} file. @sc{Cvs} uses it to keep
|
||
track of what tags are valid tag names (it is sometimes
|
||
updated when tags are used, as well as when they are
|
||
created, though).
|
||
|
||
@cindex CVSUMASK
|
||
@cindex umask, for repository files
|
||
@sc{cvs} tries to set up reasonable file permissions
|
||
for new directories that are added inside the tree, but
|
||
you must fix the permissions manually when a new
|
||
directory should have different permissions than its
|
||
parent directory. If you set the @code{CVSUMASK}
|
||
environment variable that will control the file
|
||
permissions which @sc{cvs} uses in creating directories
|
||
and/or files in the repository. @code{CVSUMASK} does
|
||
not affect the file permissions in the working
|
||
directory; such files have the permissions which are
|
||
typical for newly created files, except that sometimes
|
||
@sc{cvs} creates them read-only (see the sections on
|
||
watches, @ref{Setting a watch}; -r, @ref{Global
|
||
options}; or CVSREAD, @ref{Environment variables}).
|
||
|
||
Note that using the client/server @sc{cvs}
|
||
(@pxref{Remote repositories}), there is no good way to
|
||
set @code{CVSUMASK}; the setting on the client machine
|
||
has no effect. If you are connecting with @code{rsh}, you
|
||
can set @code{CVSUMASK} in @file{.bashrc} or @file{.cshrc}, as
|
||
described in the documentation for your operating
|
||
system. This behavior might change in future versions
|
||
of @sc{cvs}; do not rely on the setting of
|
||
@code{CVSUMASK} on the client having no effect.
|
||
@c FIXME: need to explain what a umask is or cite
|
||
@c someplace which does.
|
||
@c FIXME: Need one place which discusses this
|
||
@c read-only files thing. Why would one use -r or
|
||
@c CVSREAD? Why would one use watches? How do they interact?
|
||
@c FIXME: We need to state
|
||
@c whether using CVSUMASK removes the need for manually
|
||
@c fixing permissions (in fact, if we are going to mention
|
||
@c manually fixing permission, we better document a lot
|
||
@c better just what we mean by "fix").
|
||
|
||
@cindex setuid
|
||
@cindex setgid
|
||
Since @sc{cvs} was not written to be run setuid, it is
|
||
unsafe to try to run it setuid. You cannot use the
|
||
setuid features of @sc{rcs} together with @sc{cvs}.
|
||
|
||
@node Attic
|
||
@subsection The attic
|
||
@cindex attic
|
||
|
||
You will notice that sometimes @sc{cvs} stores an
|
||
@sc{rcs} file in the @code{Attic}. For example, if the
|
||
@sc{cvsroot} is @file{/usr/local/cvsroot} and we are
|
||
talking about the file @file{backend.c} in the
|
||
directory @file{yoyodyne/tc}, then the file normally
|
||
would be in
|
||
|
||
@example
|
||
/usr/local/cvsroot/yoyodyne/tc/backend.c,v
|
||
@end example
|
||
|
||
but if it goes in the attic, it would be in
|
||
|
||
@example
|
||
/usr/local/cvsroot/yoyodyne/tc/Attic/backend.c,v
|
||
@end example
|
||
|
||
@cindex dead state
|
||
instead. It should not matter from a user point of
|
||
view whether a file is in the attic; @sc{cvs} keeps
|
||
track of this and looks in the attic when it needs to.
|
||
But in case you want to know, the rule is that the RCS
|
||
file is stored in the attic if and only if the head
|
||
revision on the trunk has state @code{dead}. A
|
||
@code{dead} state means that file has been removed, or
|
||
never added, for that revision. For example, if you
|
||
add a file on a branch, it will have a trunk revision
|
||
in @code{dead} state, and a branch revision in a
|
||
non-@code{dead} state.
|
||
@c Probably should have some more concrete examples
|
||
@c here, or somewhere (not sure exactly how we should
|
||
@c arrange the discussion of the dead state, versus
|
||
@c discussion of the attic).
|
||
|
||
@node Working directory storage
|
||
@section How data is stored in the working directory
|
||
|
||
While we are discussing @sc{cvs} internals which may
|
||
become visible from time to time, we might as well talk
|
||
about what @sc{cvs} puts in the @file{CVS} directories
|
||
in the working directories. As with the repository,
|
||
@sc{cvs} handles this information and one can usually
|
||
access it via @sc{cvs} commands. But in some cases it
|
||
may be useful to look at it, and other programs, such
|
||
as the @code{jCVS} graphical user interface or the
|
||
@code{VC} package for emacs, may need to look at it.
|
||
Such programs should follow the recommendations in this
|
||
section if they hope to be able to work with other
|
||
programs which use those files, including future
|
||
versions of the programs just mentioned and the
|
||
command-line @sc{cvs} client.
|
||
|
||
The @file{CVS} directory contains several files.
|
||
Programs which are reading this directory should
|
||
silently ignore files which are in the directory but
|
||
which are not documented here, to allow for future
|
||
expansion.
|
||
|
||
@table @file
|
||
@item Root
|
||
This file contains the current @sc{cvs} root, as
|
||
described in @ref{Specifying a repository}.
|
||
|
||
@cindex Repository file, in CVS directory
|
||
@cindex CVS/Repository file
|
||
@item Repository
|
||
This file contains the directory within the repository
|
||
which the current directory corresponds with. For
|
||
historical reasons it is an absolute pathname, although
|
||
it would make more sense for it to be relative to the
|
||
root. For example, after the command
|
||
|
||
@example
|
||
cvs -d :local:/usr/local/cvsroot checkout yoyodyne/tc
|
||
@end example
|
||
|
||
@file{Root} will contain
|
||
|
||
@example
|
||
:local:/usr/local/cvsroot
|
||
@end example
|
||
|
||
and @file{Repository} will contain
|
||
|
||
@example
|
||
/usr/local/cvsroot/yoydyne/tc
|
||
@end example
|
||
|
||
@cindex Entries file, in CVS directory
|
||
@cindex CVS/Entries file
|
||
@item Entries
|
||
This file lists the files and directories in the
|
||
working directory. It is a text file according to the
|
||
conventions appropriate for the operating system in
|
||
question.
|
||
@c That seems like a lose, it makes it impossible (it
|
||
@c would seem) to share a working directory via a
|
||
@c networked file system between systems with diverse
|
||
@c text file conventions. But it seems to be how CVS
|
||
@c currently works.
|
||
The first character of each line indicates what sort of
|
||
line it is. If the character is unrecognized, programs
|
||
reading the file should silently skip that line, to
|
||
allow for future expansion.
|
||
|
||
If the first character is @samp{/}, then the format is:
|
||
|
||
@example
|
||
/@var{name}/@var{revision}/@var{timestamp}[+@var{conflict}]/@var{options}/@var{tagdate}
|
||
@end example
|
||
|
||
where @samp{[} and @samp{]} are not part of the entry,
|
||
but instead indicate that the @samp{+} and conflict
|
||
marker are optional. @var{name} is the name of the
|
||
file within the directory. @var{revision} is the
|
||
revision that the file in the working derives from, or
|
||
@samp{0} for an added file, or @samp{-} followed by a
|
||
revision for a removed file. @var{timestamp} is the
|
||
timestamp of the file at the time that @sc{cvs} created
|
||
it; if the timestamp differs with the actual
|
||
modification time of the file it means the file has
|
||
been modified. It is in Universal Time (UT), stored in
|
||
the format used by the ISO C asctime() function (for
|
||
example, @samp{Sun Apr 7 01:29:26 1996}). One may
|
||
write a string which is not in that format, for
|
||
example, @samp{Result of merge}, to indicate that the
|
||
file should always be considered to be modified. This
|
||
is not a special case; to see whether a file is
|
||
modified a program should take the timestamp of the file
|
||
and simply do a string compare with @var{timestamp}.
|
||
@var{conflict} indicates that there was
|
||
a conflict; if it is the same as the actual
|
||
modification time of the file it means that the user
|
||
has obviously not resolved the conflict. @var{options}
|
||
contains sticky options (for example @samp{-kb} for a
|
||
binary file). @var{tagdate} contains @samp{T} followed
|
||
by a tag name, or @samp{D} for a date, followed by a
|
||
sticky tag or date. Note that if @var{timestamp}
|
||
contains a pair of timestamps separated by a space,
|
||
rather than a single timestamp, you are dealing with a
|
||
version of @sc{cvs} earlier than @sc{cvs} 1.5 (not
|
||
documented here).
|
||
|
||
If the first character of a line in @file{Entries} is
|
||
@samp{D}, then it indicates a subdirectory. @samp{D}
|
||
on a line all by itself indicates that the program
|
||
which wrote the @file{Entries} file does record
|
||
subdirectories (therefore, if there is such a line and
|
||
no other lines beginning with @samp{D}, one knows there
|
||
are no subdirectories). Otherwise, the line looks
|
||
like:
|
||
|
||
@example
|
||
D/@var{name}/@var{filler1}/@var{filler2}/@var{filler3}/@var{filler4}
|
||
@end example
|
||
|
||
where @var{name} is the name of the subdirectory, and
|
||
all the @var{filler} fields should be silently ignored,
|
||
for future expansion. Programs which modify
|
||
@code{Entries} files should preserve these fields.
|
||
|
||
@cindex Entries.Log file, in CVS directory
|
||
@cindex CVS/Entries.Log file
|
||
@item Entries.Log
|
||
This file does not record any information beyond that
|
||
in @file{Entries}, but it does provide a way to update
|
||
the information without having to rewrite the entire
|
||
@file{Entries} file, including the ability to preserve
|
||
the information even if the program writing
|
||
@file{Entries} and @file{Entries.Log} abruptly aborts.
|
||
Programs which are reading the @file{Entries} file
|
||
should also check for @file{Entries.Log}. If the latter
|
||
exists, they should read @file{Entries} and then apply
|
||
the changes mentioned in @file{Entries.Log}. After
|
||
applying the changes, the recommended practice is to
|
||
rewrite @file{Entries} and then delete @file{Entries.Log}.
|
||
The format of a line in @file{Entries.Log} is a single
|
||
character command followed by a space followed by a
|
||
line in the format specified for a line in
|
||
@file{Entries}. The single character command is
|
||
@samp{A} to indicate that the entry is being added,
|
||
@samp{R} to indicate that the entry is being removed,
|
||
or any other character to indicate that the entire line
|
||
in @file{Entries.Log} should be silently ignored (for
|
||
future expansion). If the second character of the line
|
||
in @file{Entries.Log} is not a space, then it was
|
||
written by an older version of @sc{cvs} (not documented
|
||
here).
|
||
|
||
@cindex Entries.Backup file, in CVS directory
|
||
@cindex CVS/Entries.Backup file
|
||
@item Entries.Backup
|
||
This is a temporary file. Recommended usage is to
|
||
write a new entries file to @file{Entries.Backup}, and
|
||
then to rename it (atomically, where possible) to @file{Entries}.
|
||
|
||
@cindex Entries.Static file, in CVS directory
|
||
@cindex CVS/Entries.Static file
|
||
@item Entries.Static
|
||
The only relevant thing about this file is whether it
|
||
exists or not. If it exists, then it means that only
|
||
part of a directory was gotten and @sc{cvs} will
|
||
not create additional files in that directory. To
|
||
clear it, use the @code{update} command with the
|
||
@samp{-d} option, which will get the additional files
|
||
and remove @file{Entries.Static}.
|
||
|
||
@cindex Tag file, in CVS directory
|
||
@cindex CVS/Tag file
|
||
@cindex Sticky tags/dates, per-directory
|
||
@cindex Per-directory sticky tags/dates
|
||
@item Tag
|
||
This file contains per-directory sticky tags or dates.
|
||
The first character is @samp{T} for a branch tag,
|
||
@samp{N} for a non-branch tag, or @samp{D} for a date,
|
||
or another character to mean the file should be
|
||
silently ignored, for future expansion. This character
|
||
is followed by the tag or date. Note that
|
||
per-directory sticky tags or dates are used for things
|
||
like applying to files which are newly added; they
|
||
might not be the same as the sticky tags or dates on
|
||
individual files. For general information on sticky
|
||
tags and dates, see @ref{Sticky tags}.
|
||
@c FIXME: This needs to be much better documented,
|
||
@c preferably not in the context of "working directory
|
||
@c storage".
|
||
@c FIXME: The Sticky tags node needs to discuss, or xref to
|
||
@c someplace which discusses, per-directory sticky
|
||
@c tags and the distinction with per-file sticky tags.
|
||
|
||
@cindex Checkin.prog file, in CVS directory
|
||
@cindex CVS/Checkin.prog file
|
||
@cindex Update.prog file, in CVS directory
|
||
@cindex CVS/Update.prog file
|
||
@item Checkin.prog
|
||
@itemx Update.prog
|
||
These files store the programs specified by the
|
||
@samp{-i} and @samp{-u} options in the modules file,
|
||
respectively.
|
||
|
||
@cindex Notify file, in CVS directory
|
||
@cindex CVS/Notify file
|
||
@item Notify
|
||
This file stores notifications (for example, for
|
||
@code{edit} or @code{unedit}) which have not yet been
|
||
sent to the server. Its format is not yet documented
|
||
here.
|
||
|
||
@cindex Notify.tmp file, in CVS directory
|
||
@cindex CVS/Notify.tmp file
|
||
@item Notify.tmp
|
||
This file is to @file{Notify} as @file{Entries.Backup}
|
||
is to @file{Entries}. That is, to write @file{Notify},
|
||
first write the new contents to @file{Notify.tmp} and
|
||
then (atomically where possible), rename it to
|
||
@file{Notify}.
|
||
|
||
@cindex Base directory, in CVS directory
|
||
@cindex CVS/Base directory
|
||
@item Base
|
||
If watches are in use, then an @code{edit} command
|
||
stores the original copy of the file in the @file{Base}
|
||
directory. This allows the @code{unedit} command to
|
||
operate even if it is unable to communicate with the
|
||
server.
|
||
|
||
@cindex Template file, in CVS directory
|
||
@cindex CVS/Template file
|
||
@item Template
|
||
This file contains the template specified by the
|
||
@file{rcsinfo} file (@pxref{rcsinfo}). It is only used
|
||
by the client; the non-client/server @sc{cvs} consults
|
||
@file{rcsinfo} directly.
|
||
@end table
|
||
|
||
@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
|
||
@node Intro administrative files
|
||
@section The administrative files
|
||
@cindex Administrative files (intro)
|
||
@cindex Modules file
|
||
@cindex CVSROOT, module name
|
||
@cindex Defining modules (intro)
|
||
|
||
@c FIXME: this node should be reorganized into "general
|
||
@c information about admin files" and put the "editing
|
||
@c admin files" stuff up front rather than jumping into
|
||
@c the details of modules right away. Then the
|
||
@c Administrative files node can go away, the information
|
||
@c on each admin file distributed to a place appropriate
|
||
@c to its function, and this node can contain a table
|
||
@c listing each file and a @ref to its detailed description.
|
||
|
||
The directory @file{$CVSROOT/CVSROOT} contains some @dfn{administrative
|
||
files}. @xref{Administrative files}, for a complete description.
|
||
You can use @sc{cvs} without any of these files, but
|
||
some commands work better when at least the
|
||
@file{modules} file is properly set up.
|
||
|
||
The most important of these files is the @file{modules}
|
||
file. It defines all modules in the repository. This
|
||
is a sample @file{modules} file.
|
||
|
||
@c FIXME: The CVSROOT line is a goofy example now that
|
||
@c mkmodules doesn't exist.
|
||
@example
|
||
CVSROOT CVSROOT
|
||
modules CVSROOT modules
|
||
cvs gnu/cvs
|
||
rcs gnu/rcs
|
||
diff gnu/diff
|
||
tc yoyodyne/tc
|
||
@end example
|
||
|
||
The @file{modules} file is line oriented. In its
|
||
simplest form each line contains the name of the
|
||
module, whitespace, and the directory where the module
|
||
resides. The directory is a path relative to
|
||
@code{$CVSROOT}. The last four lines in the example
|
||
above are examples of such lines.
|
||
|
||
@c FIXME: might want to introduce the concept of options in modules file
|
||
@c (the old example which was here, -i mkmodules, is obsolete).
|
||
|
||
The line that defines the module called @samp{modules}
|
||
uses features that are not explained here.
|
||
@xref{modules}, for a full explanation of all the
|
||
available features.
|
||
|
||
@c FIXME: subsection without node is bogus
|
||
@subsection Editing administrative files
|
||
@cindex Editing administrative files
|
||
@cindex Administrative files, editing them
|
||
|
||
You edit the administrative files in the same way that you would edit
|
||
any other module. Use @samp{cvs checkout CVSROOT} to get a working
|
||
copy, edit it, and commit your changes in the normal way.
|
||
|
||
It is possible to commit an erroneous administrative
|
||
file. You can often fix the error and check in a new
|
||
revision, but sometimes a particularly bad error in the
|
||
administrative file makes it impossible to commit new
|
||
revisions.
|
||
@c @xref{Bad administrative files} for a hint
|
||
@c about how to solve such situations.
|
||
@c -- administrative file checking--
|
||
|
||
@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
|
||
@node Multiple repositories
|
||
@section Multiple repositories
|
||
@cindex Multiple repositories
|
||
@cindex Repositories, multiple
|
||
@cindex Many repositories
|
||
@cindex Parallel repositories
|
||
@cindex Disjoint repositories
|
||
@cindex CVSROOT, multiple repositories
|
||
|
||
In some situations it is a good idea to have more than
|
||
one repository, for instance if you have two
|
||
development groups that work on separate projects
|
||
without sharing any code. All you have to do to have
|
||
several repositories is to specify the appropriate
|
||
repository, using the @code{CVSROOT} environment
|
||
variable, the @samp{-d} option to @sc{cvs}, or (once
|
||
you have checked out a working directory) by simply
|
||
allowing @sc{cvs} to use the repository that was used
|
||
to check out the working directory
|
||
(@pxref{Specifying a repository}).
|
||
|
||
The big advantage of having multiple repositories is
|
||
that they can reside on different servers. The big
|
||
disadvantage is that you cannot have a single @sc{cvs}
|
||
command recurse into directories which comes from
|
||
different repositories. Generally speaking, if you are
|
||
thinking of setting up several repositories on the same
|
||
machine, you might want to consider using several
|
||
directories within the same repository.
|
||
@c FIXCVS: the thing about recursing into diverse roots
|
||
@c would be nice to fix. But it gets hairy if they are
|
||
@c on diverse servers--it isn't clear this is really
|
||
@c all that useful.
|
||
@c FIXME: Does the FAQ have more about this? I have a
|
||
@c dim recollection, but I'm too lazy to check right now.
|
||
|
||
None of the examples in this manual show multiple
|
||
repositories.
|
||
|
||
@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
|
||
@node Creating a repository
|
||
@section Creating a repository
|
||
|
||
@cindex Repository, setting up
|
||
@cindex Creating a repository
|
||
@cindex Setting up a repository
|
||
|
||
To set up a @sc{cvs} repository, first choose the
|
||
machine and disk on which you want to store the
|
||
revision history of the source files. CPU and memory
|
||
requirements are modest---a server with 32M of memory
|
||
or even less can handle a fairly large source tree with
|
||
a fair amount of activity. To estimate disk space
|
||
requirements, if you are importing RCS files from
|
||
another system, the size of those files is the
|
||
approximate initial size of your repository, or if you
|
||
are starting without any version history, a rule of
|
||
thumb is to allow for the server approximately three
|
||
times the size of the code to be under CVS for the
|
||
repository (you will eventually outgrow this, but not
|
||
for a while). On the machines on which the developers
|
||
will be working, you'll want disk space for
|
||
approximately one working directory for each developer
|
||
(either the entire tree or a portion of it, depending
|
||
on what each developer uses). Don't worry about CPU
|
||
and memory requirements for the clients---any machine
|
||
with enough capacity to run the operating system in
|
||
question should have little trouble.
|
||
@c Stuff about memory duplicates Server requirements
|
||
@c to some extent. I'm not sure this is a bad thing,
|
||
@c though (one is aimed at people who are looking into
|
||
@c this carefully, the other is aimed at people who
|
||
@c want a rule of thumb).
|
||
|
||
The repository should be accessable
|
||
(directly or via a networked file system) from all
|
||
machines which want to use @sc{cvs} in server or local
|
||
mode; the client machines need not have any access to
|
||
it other than via the @sc{cvs} protocol. It is not
|
||
possible to use @sc{cvs} to read from a repository
|
||
which one only has read access to; @sc{cvs} needs to be
|
||
able to create lock files (@pxref{Concurrency}).
|
||
|
||
@cindex init (subcommand)
|
||
To create a repository, run the @code{cvs init}
|
||
command. It will set up an empty repository in the
|
||
@sc{cvs} root specified in the usual way
|
||
(@pxref{Repository}). For example,
|
||
|
||
@example
|
||
cvs -d /usr/local/cvsroot init
|
||
@end example
|
||
|
||
@code{cvs init} is careful to never overwrite any
|
||
existing files in the repository, so no harm is done if
|
||
you run @code{cvs init} on an already set-up
|
||
repository.
|
||
|
||
@code{cvs init} will enable history logging; if you
|
||
don't want that, remove the history file after running
|
||
@code{cvs init}. @xref{history file}.
|
||
|
||
@node Backing up
|
||
@section Backing up a repository
|
||
@cindex Repository, backing up
|
||
@cindex Backing up, repository
|
||
|
||
There is nothing particularly magical about the files
|
||
in the repository; for the most part it is possible to
|
||
back them up just like any other files. However, there
|
||
are a few issues to consider.
|
||
|
||
The first is that to be paranoid, one should either not
|
||
use @sc{cvs} during the backup, or have the backup
|
||
program lock @sc{cvs} while doing the backup. To not
|
||
use @sc{cvs}, you might forbid logins to machines which
|
||
can access the repository, turn off your @sc{cvs}
|
||
server, or similar mechanisms. The details would
|
||
depend on your operating system and how you have
|
||
@sc{cvs} set up. To lock @sc{cvs}, you would create
|
||
@file{#cvs.rfl} locks in each repository directory.
|
||
See @ref{Concurrency}, for more on @sc{cvs} locks.
|
||
Having said all this, if you just back up without any
|
||
of these precautions, the results are unlikely to be
|
||
particularly dire. Restoring from backup, the
|
||
repository might be in an inconsistent state, but this
|
||
would not be particularly hard to fix manually.
|
||
|
||
When you restore a repository from backup, assuming
|
||
that changes in the repository were made after the time
|
||
of the backup, working directories which were not
|
||
affected by the failure may refer to revisions which no
|
||
longer exist in the repository. Trying to run @sc{cvs}
|
||
in such directories will typically produce an error
|
||
message. One way to get those changes back into the
|
||
repository is as follows:
|
||
|
||
@itemize @bullet
|
||
@item
|
||
Get a new working directory.
|
||
|
||
@item
|
||
Copy the files from the working directory from before
|
||
the failure over to the new working directory (do not
|
||
copy the contents of the @file{CVS} directories, of
|
||
course).
|
||
|
||
@item
|
||
Working in the new working directory, use commands such
|
||
as @code{cvs update} and @code{cvs diff} to figure out
|
||
what has changed, and then when you are ready, commit
|
||
the changes into the repository.
|
||
@end itemize
|
||
|
||
@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
|
||
@node Remote repositories
|
||
@section Remote repositories
|
||
@cindex Repositories, remote
|
||
@cindex Remote repositories
|
||
@cindex Client/Server Operation
|
||
@cindex server, CVS
|
||
|
||
Your working copy of the sources can be on a
|
||
different machine than the repository. Using @sc{cvs}
|
||
in this manner is known as @dfn{client/server}
|
||
operation. You run @sc{cvs} on a machine which can
|
||
mount your working directory, known as the
|
||
@dfn{client}, and tell it to communicate to a machine
|
||
which can mount the repository, known as the
|
||
@dfn{server}. Generally, using a remote
|
||
repository is just like using a local one, except that
|
||
the format of the repository name is:
|
||
|
||
@example
|
||
:@var{method}:@var{user}@@@var{hostname}:/path/to/repository
|
||
@end example
|
||
|
||
The details of exactly what needs to be set up depend
|
||
on how you are connecting to the server.
|
||
|
||
If @var{method} is not specified, and the repository
|
||
name contains @samp{:}, then the default is @code{ext}
|
||
or @code{server}, depending on your platform; both are
|
||
described in @ref{Connecting via rsh}.
|
||
@c Should we try to explain which platforms are which?
|
||
@c Platforms like unix and VMS, which only allow
|
||
@c privileged programs to bind to sockets <1024 lose on
|
||
@c :server:
|
||
@c Platforms like Mac and VMS, whose rsh program is
|
||
@c unusable or nonexistent, lose on :ext:
|
||
@c Platforms like OS/2 and NT probably could plausibly
|
||
@c default either way (modulo -b troubles).
|
||
|
||
@c FIXME: We need to have a better way of explaining
|
||
@c what method to use. This presentation totally
|
||
@c obscures the fact that :ext: and CVS_RSH is the way to
|
||
@c use SSH, for example. Plus it incorrectly implies
|
||
@c that you need an @code{rsh} binary on the client to use
|
||
@c :server:.
|
||
@menu
|
||
* Server requirements:: Memory and other resources for servers
|
||
* Connecting via rsh:: Using the @code{rsh} program to connect
|
||
* Password authenticated:: Direct connections using passwords
|
||
* Kerberos authenticated:: Direct connections with kerberos
|
||
@end menu
|
||
|
||
@node Server requirements
|
||
@subsection Server requirements
|
||
|
||
The quick answer to what sort of machine is suitable as
|
||
a server is that requirements are modest---a server
|
||
with 32M of memory or even less can handle a fairly
|
||
large source tree with a fair amount of activity.
|
||
@c Say something about CPU speed too? I'm even less sure
|
||
@c what to say on that subject...
|
||
|
||
The real answer, of course, is more complicated. The
|
||
@sc{cvs} server consists of two processes for each
|
||
client that it is serving. Memory consumption on the
|
||
child process should remain fairly small. Memory
|
||
consumption on the parent process, particularly if the
|
||
network connection to the client is slow, can be
|
||
expected to grow to slightly more than the size of the
|
||
sources in a single directory, or two megabytes,
|
||
whichever is larger.
|
||
@c "two megabytes" of course is SERVER_HI_WATER. But
|
||
@c we don't mention that here because we are
|
||
@c documenting the default configuration of CVS. If it
|
||
@c is a "standard" thing to change that value, it
|
||
@c should be some kind of run-time configuration.
|
||
@c
|
||
@c See cvsclient.texi for more on the design decision
|
||
@c to not have locks in place while waiting for the
|
||
@c client, which is what results in memory consumption
|
||
@c as high as this.
|
||
|
||
Multiplying the size of each @sc{cvs} server by the
|
||
number of servers which you expect to have active at
|
||
one time should give an idea of memory requirements for
|
||
the server. For the most part, the memory consumed by
|
||
the parent process probably can be swap space rather
|
||
than physical memory.
|
||
@c Has anyone verified that notion about swap space?
|
||
@c I say it based pretty much on guessing that the
|
||
@c ->text of the struct buffer_data only gets accessed
|
||
@c in a first in, first out fashion, but I haven't
|
||
@c looked very closely.
|
||
|
||
Resource consumption for the client or the
|
||
non-client/server @sc{cvs} is even more modest---any
|
||
machine with enough capacity to run the operating system
|
||
in question should have little trouble.
|
||
@c Probably we could be saying more about this.
|
||
@c I would guess for non-client/server CVS in an NFS
|
||
@c environment the biggest issues is the network and
|
||
@c the NFS server.
|
||
|
||
@node Connecting via rsh
|
||
@subsection Connecting with rsh
|
||
|
||
@cindex rsh
|
||
CVS uses the @file{rsh} protocol to perform these
|
||
operations, so the remote user host needs to have a
|
||
@file{.rhosts} file which grants access to the local
|
||
user.
|
||
|
||
For example, suppose you are the user @file{mozart} on
|
||
the local machine @file{toe.grunge.com}, and the
|
||
server machine is @file{chainsaw.yard.com}. On
|
||
chainsaw, put the following line into the file
|
||
@file{.rhosts} in @file{bach}'s home directory:
|
||
|
||
@example
|
||
toe.grunge.com mozart
|
||
@end example
|
||
|
||
Then test that @code{rsh} is working with
|
||
|
||
@example
|
||
rsh -l bach chainsaw.yard.com 'echo $PATH'
|
||
@end example
|
||
|
||
@cindex CVS_SERVER
|
||
Next you have to make sure that @code{rsh} will be able
|
||
to find the server. Make sure that the path which
|
||
@code{rsh} printed in the above example includes the
|
||
directory containing a program named @code{cvs} which
|
||
is the server. You need to set the path in
|
||
@file{.bashrc}, @file{.cshrc}, etc., not @file{.login}
|
||
or @file{.profile}. Alternately, you can set the
|
||
environment variable @code{CVS_SERVER} on the client
|
||
machine to the filename of the server you want to use,
|
||
for example @file{/usr/local/bin/cvs-1.6}.
|
||
@c FIXME: there should be a way to specify the
|
||
@c program in CVSROOT, not CVS_SERVER, so that one can use
|
||
@c different ones for different roots. e.g. ":server;cvs=cvs-1.6:"
|
||
@c instead of ":server:".
|
||
|
||
There is no need to edit @code{inetd.conf} or start a
|
||
@sc{cvs} server daemon.
|
||
|
||
@cindex :server:
|
||
@cindex :ext:
|
||
There are two access methods that you use in CVSROOT
|
||
for rsh. @code{:server:} specifies an internal rsh
|
||
client, which is supported only by some CVS ports.
|
||
@code{:ext:} specifies an external rsh program. By
|
||
default this is @code{rsh} but you may set the
|
||
@code{CVS_RSH} environment variable to invoke another
|
||
program which can access the remote server (for
|
||
example, @code{remsh} on HP-UX 9 because @code{rsh} is
|
||
something different). It must be a program which can
|
||
transmit data to and from the server without modifying
|
||
it; for example the Windows NT @code{rsh} is not
|
||
suitable since it by default translates between CRLF
|
||
and LF. The OS/2 CVS port has a hack to pass @samp{-b}
|
||
to @code{rsh} to get around this, but since this could
|
||
potentially cause problems for programs other than the
|
||
standard @code{rsh}, it may change in the future. If
|
||
you set @code{CVS_RSH} to @code{SSH} or some other rsh
|
||
replacement, the instructions in the rest of this
|
||
section concerning @file{.rhosts} and so on are likely
|
||
to be inapplicable; consult the documentation for your rsh
|
||
replacement.
|
||
@c FIXME: there should be a way to specify the
|
||
@c program in CVSROOT, not CVS_RSH, so that one can use
|
||
@c different ones for different roots. e.g. ":ext;rsh=remsh:"
|
||
@c instead of ":ext:".
|
||
@c See also the comment in src/client.c for rationale
|
||
@c concerning "rsh" being the default and never
|
||
@c "remsh".
|
||
|
||
Continuing our example, supposing you want to access
|
||
the module @file{foo} in the repository
|
||
@file{/usr/local/cvsroot/}, on machine
|
||
@file{chainsaw.yard.com}, you are ready to go:
|
||
|
||
@example
|
||
cvs -d :ext:bach@@chainsaw.yard.com:/usr/local/cvsroot checkout foo
|
||
@end example
|
||
|
||
(The @file{bach@@} can be omitted if the username is
|
||
the same on both the local and remote hosts.)
|
||
|
||
@c Should we mention "rsh host echo hi" and "rsh host
|
||
@c cat" (the latter followed by typing text and ^D)
|
||
@c as troubleshooting techniques? Probably yes
|
||
@c (people tend to have trouble setting this up),
|
||
@c but this kind of thing can be hard to spell out.
|
||
|
||
@node Password authenticated
|
||
@subsection Direct connection with password authentication
|
||
|
||
The @sc{cvs} client can also connect to the server
|
||
using a password protocol. This is particularly useful
|
||
if using @code{rsh} is not feasible (for example,
|
||
the server is behind a firewall), and Kerberos also is
|
||
not available.
|
||
|
||
To use this method, it is necessary to make
|
||
some adjustments on both the server and client sides.
|
||
|
||
@menu
|
||
* Password authentication server:: Setting up the server
|
||
* Password authentication client:: Using the client
|
||
* Password authentication security:: What this method does and does not do
|
||
@end menu
|
||
|
||
@node Password authentication server
|
||
@subsubsection Setting up the server for password authentication
|
||
|
||
@cindex Pserver (subcommand)
|
||
@cindex password server, setting up
|
||
@cindex authenticating server, setting up
|
||
@c FIXME: this isn't quite right regarding port
|
||
@c numbers; CVS looks up "cvspserver" in
|
||
@c /etc/services (on unix, but what about non-unix?).
|
||
On the server side, the file @file{/etc/inetd.conf}
|
||
needs to be edited so @code{inetd} knows to run the
|
||
command @code{cvs pserver} when it receives a
|
||
connection on the right port. By default, the port
|
||
number is 2401; it would be different if your client
|
||
were compiled with @code{CVS_AUTH_PORT} defined to
|
||
something else, though.
|
||
|
||
If your @code{inetd} allows raw port numbers in
|
||
@file{/etc/inetd.conf}, then the following (all on a
|
||
single line in @file{inetd.conf}) should be sufficient:
|
||
|
||
@example
|
||
2401 stream tcp nowait root /usr/local/bin/cvs
|
||
cvs -b /usr/local/bin pserver
|
||
@end example
|
||
|
||
The @samp{-b} option specifies the directory which contains
|
||
the @sc{rcs} binaries on the server. You could also use the
|
||
@samp{-T} option to specify a temporary directory.
|
||
|
||
If your @code{inetd} wants a symbolic service
|
||
name instead of a raw port number, then put this in
|
||
@file{/etc/services}:
|
||
|
||
@example
|
||
cvspserver 2401/tcp
|
||
@end example
|
||
|
||
and put @code{cvspserver} instead of
|
||
@code{2401} in @file{inetd.conf}.
|
||
|
||
Once the above is taken care of, restart your
|
||
@code{inetd}, or do whatever is necessary to force it
|
||
to reread its initialization files.
|
||
|
||
@c FIXME: should be documenting how to troubleshoot
|
||
@c this. One strange situation I ran into recently
|
||
@c was that if inetd.conf specifies a non-existent
|
||
@c cvs (e.g. /usr/local/bin/cvs doesn't exist in
|
||
@c the above example), the client says
|
||
@c cvs-1.8 [login aborted]: unrecognized auth response from harvey:
|
||
@c which is a very unhelpful response (can it be
|
||
@c improved? does inetd log somewhere?)
|
||
|
||
@cindex CVS passwd file
|
||
@cindex passwd (admin file)
|
||
Because the client stores and transmits passwords in
|
||
cleartext (almost---see @ref{Password authentication
|
||
security}, for details), a separate @sc{cvs} password
|
||
file may be used, so people don't compromise their
|
||
regular passwords when they access the repository.
|
||
This file is @file{$CVSROOT/CVSROOT/passwd}
|
||
(@pxref{Intro administrative files}). Its format is
|
||
similar to @file{/etc/passwd}, except that it only has
|
||
two fields, username and password. For example:
|
||
|
||
@example
|
||
bach:ULtgRLXo7NRxs
|
||
cwang:1sOp854gDF3DY
|
||
@end example
|
||
|
||
The password is encrypted according to the standard
|
||
Unix @code{crypt()} function, so it is possible to
|
||
paste in passwords directly from regular Unix
|
||
@file{passwd} files.
|
||
|
||
When authenticating a password, the server first checks
|
||
for the user in the @sc{cvs} @file{passwd} file. If it
|
||
finds the user, it compares against that password. If
|
||
it does not find the user, or if the @sc{cvs}
|
||
@file{passwd} file does not exist, then the server
|
||
tries to match the password using the system's
|
||
user-lookup routine. When using the @sc{cvs}
|
||
@file{passwd} file, the server runs under as the
|
||
username specified in the the third argument in the
|
||
entry, or as the first argument if there is no third
|
||
argument (in this way @sc{cvs} allows imaginary
|
||
usernames provided the @sc{cvs} @file{passwd} file
|
||
indicates corresponding valid system usernames). In
|
||
any case, @sc{cvs} will have no privileges which the
|
||
(valid) user would not have.
|
||
|
||
@cindex user aliases
|
||
It is possible to ``map'' cvs-specific
|
||
usernames onto system usernames (i.e., onto system
|
||
login names) in the @file{$CVSROOT/CVSROOT/passwd} file
|
||
by appending a colon and the system username after the
|
||
password. For example:
|
||
|
||
@example
|
||
cvs:ULtgRLXo7NRxs:kfogel
|
||
generic:1sOp854gDF3DY:spwang
|
||
anyone:1sOp854gDF3DY:spwang
|
||
@end example
|
||
|
||
Thus, someone remotely accessing the repository
|
||
on @file{chainsaw.yard.com} with the following
|
||
command:
|
||
|
||
@example
|
||
cvs -d :pserver:cvs@@chainsaw.yard.com:/usr/local/cvsroot checkout foo
|
||
@end example
|
||
|
||
would end up running the server under the
|
||
system identity kfogel, assuming successful
|
||
authentication. However, the remote user would not
|
||
necessarily need to know kfogel's system password, as
|
||
the @file{$CVSROOT/CVSROOT/passwd} file might contain a
|
||
different password, used only for @sc{cvs}. And as the
|
||
example above indicates, it is permissible to map
|
||
multiple cvs usernames onto a single system username.
|
||
|
||
This feature is designed to allow people
|
||
repository access without full system access (in
|
||
particular, see @xref{Read-only access}); however, also
|
||
@xref{Password authentication security}. Any sort of
|
||
repository access very likely implies a degree of
|
||
general system access as well.
|
||
|
||
Right now, the only way to put a password in the
|
||
@sc{cvs} @file{passwd} file is to paste it there from
|
||
somewhere else. Someday, there may be a @code{cvs
|
||
passwd} command.
|
||
@c We might also suggest using the @code{htpasswd} command
|
||
@c from freely available web servers as well, but that
|
||
@c would open up a can of worms in that the users next
|
||
@c questions are likely to be "where do I get it?" and
|
||
@c "how do I use it?"
|
||
|
||
@node Password authentication client
|
||
@subsubsection Using the client with password authentication
|
||
@cindex Login (subcommand)
|
||
@cindex password client, using
|
||
@cindex authenticated client, using
|
||
@cindex :pserver:
|
||
Before connecting to the server, the client must @dfn{log
|
||
in} with the command @code{cvs login}. Logging in
|
||
verifies a password with the server, and also records
|
||
the password for later transactions with the server.
|
||
The @code{cvs login} command needs to know the
|
||
username, server hostname, and full repository path,
|
||
and it gets this information from the repository
|
||
argument or the @code{CVSROOT} environment variable.
|
||
|
||
@code{cvs login} is interactive --- it prompts for a
|
||
password:
|
||
|
||
@example
|
||
cvs -d :pserver:bach@@chainsaw.yard.com:/usr/local/cvsroot login
|
||
CVS password:
|
||
@end example
|
||
|
||
The password is checked with the server; if it is
|
||
correct, the @code{login} succeeds, else it fails,
|
||
complaining that the password was incorrect.
|
||
|
||
Once you have logged in, you can force @sc{cvs} to
|
||
connect directly to the server and authenticate with
|
||
the stored password:
|
||
|
||
@example
|
||
cvs -d :pserver:bach@@chainsaw.yard.com:/usr/local/cvsroot checkout foo
|
||
@end example
|
||
|
||
The @samp{:pserver:} is necessary because without it,
|
||
@sc{cvs} will assume it should use @code{rsh} to
|
||
connect with the server (@pxref{Connecting via rsh}).
|
||
(Once you have a working copy checked out and are
|
||
running @sc{cvs} commands from within it, there is no
|
||
longer any need to specify the repository explicitly,
|
||
because @sc{cvs} records it in the working copy's
|
||
@file{CVS} subdirectory.)
|
||
|
||
@cindex CVS_PASSFILE, environment variable
|
||
Passwords are stored by default in the file
|
||
@file{$HOME/.cvspass}. Its format is human-readable,
|
||
but don't edit it unless you know what you are doing.
|
||
The passwords are not stored in cleartext, but are
|
||
trivially encoded to protect them from "innocent"
|
||
compromise (i.e., inadvertently being seen by a system
|
||
administrator who happens to look at that file).
|
||
|
||
@c FIXME: seems to me this needs somewhat more
|
||
@c explanation.
|
||
@cindex Logout (subcommand)
|
||
The password for the currently choosen remote repository
|
||
can be removed from the CVS_PASSFILE by using the
|
||
@code{cvs logout} command.
|
||
|
||
The @code{CVS_PASSFILE} environment variable overrides
|
||
this default. If you use this variable, make sure you
|
||
set it @emph{before} @code{cvs login} is run. If you
|
||
were to set it after running @code{cvs login}, then
|
||
later @sc{cvs} commands would be unable to look up the
|
||
password for transmission to the server.
|
||
|
||
@node Password authentication security
|
||
@subsubsection Security considerations with password authentication
|
||
|
||
The passwords are stored on the client side in a
|
||
trivial encoding of the cleartext, and transmitted in
|
||
the same encoding. The encoding is done only to
|
||
prevent inadvertent password compromises (i.e., a
|
||
system administrator accidentally looking at the file),
|
||
and will not prevent even a naive attacker from gaining
|
||
the password.
|
||
|
||
@c FIXME: The bit about "access to the repository
|
||
@c implies general access to the system is *not* specific
|
||
@c to pserver; it applies to kerberos and SSH and
|
||
@c everything else too. Should reorganize the
|
||
@c documentation to make this clear.
|
||
The separate @sc{cvs} password file (@pxref{Password
|
||
authentication server}) allows people
|
||
to use a different password for repository access than
|
||
for login access. On the other hand, once a user has
|
||
access to the repository, she can execute programs on
|
||
the server system through a variety of means. Thus, repository
|
||
access implies fairly broad system access as well. It
|
||
might be possible to modify @sc{cvs} to prevent that,
|
||
but no one has done so as of this writing.
|
||
@c OpenBSD uses chroot() and copies the repository to
|
||
@c provide anonymous read-only access (for details see
|
||
@c http://www.openbsd.org/anoncvs.shar). While this
|
||
@c closes the most obvious holes, I'm not sure it
|
||
@c closes enough holes to recommend it (plus it is
|
||
@c *very* easy to accidentally screw up a setup of this
|
||
@c type).
|
||
Furthermore, there may be other ways in which having
|
||
access to @sc{cvs} allows people to gain more general
|
||
access to the system; noone has done a careful audit.
|
||
|
||
In summary, anyone who gets the password gets
|
||
repository access, and some measure of general system
|
||
access as well. The password is available to anyone
|
||
who can sniff network packets or read a protected
|
||
(i.e., user read-only) file. If you want real
|
||
security, get Kerberos.
|
||
|
||
@node Kerberos authenticated
|
||
@subsection Direct connection with kerberos
|
||
|
||
@cindex kerberos
|
||
@cindex :kserver:
|
||
The main disadvantage of using rsh is that all the data
|
||
needs to pass through additional programs, so it may be
|
||
slower. So if you have kerberos installed you can
|
||
connect via a direct @sc{tcp} connection,
|
||
authenticating with kerberos.
|
||
|
||
To do this, @sc{cvs} needs to be compiled with kerberos
|
||
support; when configuring @sc{cvs} it tries to detect
|
||
whether kerberos is present or you can use the
|
||
@file{--with-krb4} flag to configure.
|
||
|
||
The data transmitted is @emph{not} encrypted by
|
||
default. Encryption support must be compiled into both
|
||
the client and server; use the
|
||
@file{--enable-encryption} configure option to turn it
|
||
on. You must then use the @code{-x} global option to
|
||
request encryption.
|
||
|
||
@cindex CVS_CLIENT_PORT
|
||
You need to edit @code{inetd.conf} on the server
|
||
machine to run @code{cvs kserver}. The client uses
|
||
port 1999 by default; if you want to use another port
|
||
specify it in the @code{CVS_CLIENT_PORT} environment
|
||
variable on the client.
|
||
|
||
@cindex kinit
|
||
When you want to use @sc{cvs}, get a ticket in the
|
||
usual way (generally @code{kinit}); it must be a ticket
|
||
which allows you to log into the server machine. Then
|
||
you are ready to go:
|
||
|
||
@example
|
||
cvs -d :kserver:chainsaw.yard.com:/user/local/cvsroot checkout foo
|
||
@end example
|
||
|
||
Previous versions of @sc{cvs} would fall back to a
|
||
connection via rsh; this version will not do so.
|
||
|
||
@c ---------------------------------------------------------------------
|
||
@node Read-only access
|
||
@section Read-only repository access
|
||
@cindex read-only repository access
|
||
@cindex readers (admin file)
|
||
@cindex writers (admin file)
|
||
|
||
It is possible to grant read-only repository
|
||
access to people using the password-authenticated
|
||
server (@pxref{Password authenticated}). (The
|
||
other access methods do not have explicit support for
|
||
read-only users because those methods all assume login
|
||
access to the repository machine anyway, and therefore
|
||
the user can do whatever local file permissions allow
|
||
her to do.)
|
||
|
||
A user who has read-only access can do only
|
||
those @sc{cvs} operations which do not modify the
|
||
repository, except for certain ``administrative'' files
|
||
(such as lock files and the history file). It may be
|
||
desirable to use this feature in conjunction with
|
||
user-aliasing (@pxref{Password authentication server}).
|
||
However, note that read-only access does not repeal the
|
||
existing security considerations in @xref{Password
|
||
authentication security}.
|
||
|
||
There are two ways to specify read-only access
|
||
for a user: by inclusion, and by exclusion.
|
||
|
||
"Inclusion" means listing that user
|
||
specifically in the @file{$CVSROOT/CVSROOT/readers}
|
||
file, which is simply a newline-separated list of
|
||
users. Here is a sample @file{readers} file:
|
||
|
||
@example
|
||
melissa
|
||
splotnik
|
||
jrandom
|
||
@end example
|
||
|
||
(Don't forget the newline after the last user.)
|
||
|
||
"Exclusion" means explicitly listing everyone
|
||
who has @emph{write} access---if the file
|
||
|
||
@example
|
||
$CVSROOT/CVSROOT/writers
|
||
@end example
|
||
|
||
@noindent
|
||
exists, then only
|
||
those users listed in it have write access, and
|
||
everyone else has read-only access (of course, even the
|
||
read-only users still need to be listed in the
|
||
@sc{cvs} @file{passwd} file). The
|
||
@file{writers} file has the same format as the
|
||
@file{readers} file.
|
||
|
||
Note: if your @sc{cvs} @file{passwd}
|
||
file maps cvs users onto system users (@pxref{Password
|
||
authentication server}), make sure you deny or grant
|
||
read-only access using the @emph{cvs} usernames, not
|
||
the system usernames. That is, the @file{readers} and
|
||
@file{writers} files contain cvs usernames, which may
|
||
or may not be the same as system usernames.
|
||
|
||
Here is a complete description of the server's
|
||
behavior in deciding whether to grant read-only or
|
||
read-write access:
|
||
|
||
If @file{readers} exists, and this user is
|
||
listed in it, then she gets read-only access. Or if
|
||
@file{writers} exists, and this user is NOT listed in
|
||
it, then she also gets read-only access (this is true
|
||
even if @file{readers} exists but she is not listed
|
||
there). Otherwise, she gets full read-write access.
|
||
|
||
Of course there is a conflict if the user is
|
||
listed in both files. This is resolved in the more
|
||
conservative way, it being better to protect the
|
||
repository too much than too little: such a user gets
|
||
read-only access.
|
||
|
||
@node Server temporary directory
|
||
@section Temporary directories for the server
|
||
@cindex temporary directories, and server
|
||
@cindex server, temporary directories
|
||
|
||
While running, the @sc{cvs} server creates temporary
|
||
directories. They are named
|
||
|
||
@example
|
||
cvs-serv@var{pid}
|
||
@end example
|
||
|
||
@noindent
|
||
where @var{pid} is the process identification number of
|
||
the server. They are located in the directory
|
||
specified by the @samp{TMPDIR} environment variable
|
||
(@pxref{Environment variables}), the @samp{-T} global
|
||
option (@pxref{Global options}), or failing that
|
||
@file{/tmp}.
|
||
|
||
In most cases the server will remove the temporary
|
||
directory when it is done, whether it finishes normally
|
||
or abnormally. However, there are a few cases in which
|
||
the server does not or cannot remove the temporary
|
||
directory, for example:
|
||
|
||
@itemize @bullet
|
||
@item
|
||
If the server aborts due to an internal server error,
|
||
it may preserve the directory to aid in debugging
|
||
|
||
@item
|
||
If the server is killed in a way that it has no way of
|
||
cleaning up (most notably, @samp{kill -KILL} on unix).
|
||
|
||
@item
|
||
If the system shuts down without an orderly shutdown,
|
||
which tells the server to clean up.
|
||
@end itemize
|
||
|
||
In cases such as this, you will need to manually remove
|
||
the @file{cvs-serv@var{pid}} directories. As long as
|
||
there is no server running with process identification
|
||
number @var{pid}, it is safe to do so.
|
||
|
||
@c ---------------------------------------------------------------------
|
||
@node Starting a new project
|
||
@chapter Starting a project with CVS
|
||
@cindex Starting a project with CVS
|
||
@cindex Creating a project
|
||
|
||
@comment --moduledb--
|
||
Because renaming files and moving them between
|
||
directories is somewhat inconvenient, the first thing
|
||
you do when you start a new project should be to think
|
||
through your file organization. It is not impossible
|
||
to rename or move files, but it does increase the
|
||
potential for confusion and @sc{cvs} does have some
|
||
quirks particularly in the area of renaming
|
||
directories. @xref{Moving files}.
|
||
|
||
What to do next depends on the situation at hand.
|
||
|
||
@menu
|
||
* Setting up the files:: Getting the files into the repository
|
||
* Defining the module:: How to make a module of the files
|
||
@end menu
|
||
@c -- File permissions!
|
||
|
||
@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
|
||
@node Setting up the files
|
||
@section Setting up the files
|
||
|
||
The first step is to create the files inside the repository. This can
|
||
be done in a couple of different ways.
|
||
|
||
@c -- The contributed scripts
|
||
@menu
|
||
* From files:: This method is useful with old projects
|
||
where files already exists.
|
||
* From other version control systems:: Old projects where you want to
|
||
preserve history from another system.
|
||
* From scratch:: Creating a directory tree from scratch.
|
||
@end menu
|
||
|
||
@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
|
||
@node From files
|
||
@subsection Creating a directory tree from a number of files
|
||
@cindex Importing files
|
||
|
||
When you begin using @sc{cvs}, you will probably already have several
|
||
projects that can be
|
||
put under @sc{cvs} control. In these cases the easiest way is to use the
|
||
@code{import} command. An example is probably the easiest way to
|
||
explain how to use it. If the files you want to install in
|
||
@sc{cvs} reside in @file{@var{wdir}}, and you want them to appear in the
|
||
repository as @file{$CVSROOT/yoyodyne/@var{rdir}}, you can do this:
|
||
|
||
@example
|
||
$ cd @var{wdir}
|
||
$ cvs import -m "Imported sources" yoyodyne/@var{rdir} yoyo start
|
||
@end example
|
||
|
||
Unless you supply a log message with the @samp{-m}
|
||
flag, @sc{cvs} starts an editor and prompts for a
|
||
message. The string @samp{yoyo} is a @dfn{vendor tag},
|
||
and @samp{start} is a @dfn{release tag}. They may fill
|
||
no purpose in this context, but since @sc{cvs} requires
|
||
them they must be present. @xref{Tracking sources}, for
|
||
more information about them.
|
||
|
||
You can now verify that it worked, and remove your
|
||
original source directory.
|
||
@c FIXME: Need to say more about "verify that it
|
||
@c worked". What should the user look for in the output
|
||
@c from "diff -r"?
|
||
|
||
@example
|
||
$ cd ..
|
||
$ mv @var{dir} @var{dir}.orig
|
||
$ cvs checkout yoyodyne/@var{dir} # @r{Explanation below}
|
||
$ diff -r @var{dir}.orig yoyodyne/@var{dir}
|
||
$ rm -r @var{dir}.orig
|
||
@end example
|
||
|
||
@noindent
|
||
Erasing the original sources is a good idea, to make sure that you do
|
||
not accidentally edit them in @var{dir}, bypassing @sc{cvs}.
|
||
Of course, it would be wise to make sure that you have
|
||
a backup of the sources before you remove them.
|
||
|
||
The @code{checkout} command can either take a module
|
||
name as argument (as it has done in all previous
|
||
examples) or a path name relative to @code{$CVSROOT},
|
||
as it did in the example above.
|
||
|
||
It is a good idea to check that the permissions
|
||
@sc{cvs} sets on the directories inside @samp{$CVSROOT}
|
||
are reasonable, and that they belong to the proper
|
||
groups. @xref{File permissions}.
|
||
|
||
If some of the files you want to import are binary, you
|
||
may want to use the wrappers features to specify which
|
||
files are binary and which are not. @xref{Wrappers}.
|
||
|
||
@c The node name is too long, but I am having trouble
|
||
@c thinking of something more concise.
|
||
@node From other version control systems
|
||
@subsection Creating Files From Other Version Control Systems
|
||
@cindex Importing files, from other version control systems
|
||
|
||
If you have a project which you are maintaining with
|
||
another version control system, such as @sc{rcs}, you
|
||
may wish to put the files from that project into
|
||
@sc{cvs}, and preserve the revision history of the
|
||
files.
|
||
|
||
@table @asis
|
||
@cindex RCS, importing files from
|
||
@item From RCS
|
||
If you have been using @sc{rcs}, find the @sc{rcs}
|
||
files---usually a file named @file{foo.c} will have its
|
||
@sc{rcs} file in @file{RCS/foo.c,v} (but it could be
|
||
other places; consult the @sc{rcs} documentation for
|
||
details). Then create the appropriate directories in
|
||
@sc{cvs} if they do not already exist. Then copy the
|
||
files into the appropriate directories in the @sc{cvs}
|
||
repository (the name in the repository must be the name
|
||
of the source file with @samp{,v} added; the files go
|
||
directly in the appopriate directory of the repository,
|
||
not in an @file{RCS} subdirectory). This is one of the
|
||
few times when it is a good idea to access the @sc{cvs}
|
||
repository directly, rather than using @sc{cvs}
|
||
commands. Then you are ready to check out a new
|
||
working directory.
|
||
@c Someday there probably should be a "cvs import -t
|
||
@c rcs" or some such. It could even create magic
|
||
@c branches. It could also do something about the case
|
||
@c where the RCS file had a (non-magic) "0" branch.
|
||
|
||
The @sc{rcs} file should not be locked when you move it
|
||
into @sc{cvs}; if it is, @sc{cvs} will have trouble
|
||
letting you operate on it.
|
||
@c What is the easiest way to unlock your files if you
|
||
@c have them locked? Especially if you have a lot of them?
|
||
@c This is a CVS bug/misfeature; importing RCS files
|
||
@c should ignore whether they are locked and leave them in
|
||
@c an unlocked state. Yet another reason for a separate
|
||
@c "import RCS file" command.
|
||
|
||
@c How many is "many"? Or do they just import RCS files?
|
||
@item From another version control system
|
||
Many version control systems have the ability to export
|
||
@sc{rcs} files in the standard format. If yours does,
|
||
export the @sc{rcs} files and then follow the above
|
||
instructions.
|
||
|
||
@cindex SCCS, importing files from
|
||
@item From SCCS
|
||
There is a script in the @file{contrib} directory of
|
||
the @sc{cvs} source distribution called @file{sccs2rcs}
|
||
which converts @sc{sccs} files to @sc{rcs} files.
|
||
Note: you must run it on a machine which has both
|
||
@sc{sccs} and @sc{rcs} installed, and like everything
|
||
else in contrib it is unsupported (your mileage may
|
||
vary).
|
||
@end table
|
||
@c CMZ and/or PATCHY were systems that were used in the
|
||
@c high energy physics community (especially for
|
||
@c CERNLIB). CERN has replaced them with CVS, but the
|
||
@c CAR format seems to live on as a way to submit
|
||
@c changes. There is a program car2cvs which converts
|
||
@c but I'm not sure where one gets a copy.
|
||
@c Not sure it is worth mentioning here, since it would
|
||
@c appear to affect only one particular community.
|
||
@c Best page for more information is:
|
||
@c http://wwwcn1.cern.ch/asd/cvs/index.html
|
||
@c See also:
|
||
@c http://ecponion.cern.ch/ecpsa/cernlib.html
|
||
|
||
@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
|
||
@node From scratch
|
||
@subsection Creating a directory tree from scratch
|
||
|
||
@c Also/instead should be documenting
|
||
@c $ cvs co -l .
|
||
@c $ mkdir tc
|
||
@c $ cvs add tc
|
||
@c $ cd tc
|
||
@c $ mkdir man
|
||
@c $ cvs add man
|
||
@c etc.
|
||
@c Using import to create the directories only is
|
||
@c probably a somewhat confusing concept.
|
||
For a new project, the easiest thing to do is probably
|
||
to create an empty directory structure, like this:
|
||
|
||
@example
|
||
$ mkdir tc
|
||
$ mkdir tc/man
|
||
$ mkdir tc/testing
|
||
@end example
|
||
|
||
After that, you use the @code{import} command to create
|
||
the corresponding (empty) directory structure inside
|
||
the repository:
|
||
|
||
@example
|
||
$ cd tc
|
||
$ cvs import -m "Created directory structure" yoyodyne/@var{dir} yoyo start
|
||
@end example
|
||
|
||
Then, use @code{add} to add files (and new directories)
|
||
as they appear.
|
||
|
||
Check that the permissions @sc{cvs} sets on the
|
||
directories inside @samp{$CVSROOT} are reasonable.
|
||
|
||
@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
|
||
@node Defining the module
|
||
@section Defining the module
|
||
@cindex Defining a module
|
||
@cindex Editing the modules file
|
||
@cindex Module, defining
|
||
@cindex Modules file, changing
|
||
|
||
The next step is to define the module in the
|
||
@file{modules} file. This is not strictly necessary,
|
||
but modules can be convenient in grouping together
|
||
related files and directories.
|
||
|
||
In simple cases these steps are sufficient to define a module.
|
||
|
||
@enumerate
|
||
@item
|
||
Get a working copy of the modules file.
|
||
|
||
@example
|
||
$ cvs checkout CVSROOT/modules
|
||
$ cd CVSROOT
|
||
@end example
|
||
|
||
@item
|
||
Edit the file and insert a line that defines the module. @xref{Intro
|
||
administrative files}, for an introduction. @xref{modules}, for a full
|
||
description of the modules file. You can use the
|
||
following line to define the module @samp{tc}:
|
||
|
||
@example
|
||
tc yoyodyne/tc
|
||
@end example
|
||
|
||
@item
|
||
Commit your changes to the modules file.
|
||
|
||
@example
|
||
$ cvs commit -m "Added the tc module." modules
|
||
@end example
|
||
|
||
@item
|
||
Release the modules module.
|
||
|
||
@example
|
||
$ cd ..
|
||
$ cvs release -d CVSROOT
|
||
@end example
|
||
@end enumerate
|
||
|
||
@c ---------------------------------------------------------------------
|
||
@node Multiple developers
|
||
@chapter Multiple developers
|
||
@cindex Multiple developers
|
||
@cindex Team of developers
|
||
@cindex File locking
|
||
@cindex Locking files
|
||
@cindex Working copy
|
||
@cindex reserved checkouts
|
||
@cindex unreserved checkouts
|
||
@cindex RCS-style locking
|
||
|
||
When more than one person works on a software project
|
||
things often get complicated. Often, two people try to
|
||
edit the same file simultaneously. One solution, known
|
||
as @dfn{file locking} or @dfn{reserved checkouts}, is
|
||
to allow only one person to edit each file at a time.
|
||
This is the only solution with some version control
|
||
systems, including @sc{rcs} and @sc{sccs}. Currently
|
||
the usual way to get reserved checkouts with @sc{cvs}
|
||
is the @code{cvs admin -l} command (@pxref{admin
|
||
options}). This is not as nicely integrated into
|
||
@sc{cvs} as the watch features, described below, but it
|
||
seems that most people with a need for reserved
|
||
checkouts find it adequate.
|
||
@c Or "find it better than worrying about implementing
|
||
@c nicely integrated reserved checkouts" or ...?
|
||
It also may be possible to use the watches
|
||
features described below, together with suitable
|
||
procedures (not enforced by software), to avoid having
|
||
two people edit at the same time.
|
||
|
||
@c Our unreserved checkout model might not
|
||
@c be quite the same as others. For example, I
|
||
@c think that some systems will tend to create a branch
|
||
@c in the case where CVS prints "up-to-date check failed".
|
||
@c It isn't clear to me whether we should try to
|
||
@c explore these subtleties; it could easily just
|
||
@c confuse people.
|
||
The default model with @sc{cvs} is known as
|
||
@dfn{unreserved checkouts}. In this model, developers
|
||
can edit their own @dfn{working copy} of a file
|
||
simultaneously. The first person that commits his
|
||
changes has no automatic way of knowing that another
|
||
has started to edit it. Others will get an error
|
||
message when they try to commit the file. They must
|
||
then use @sc{cvs} commands to bring their working copy
|
||
up to date with the repository revision. This process
|
||
is almost automatic.
|
||
|
||
@c FIXME? should probably use the word "watch" here, to
|
||
@c tie this into the text below and above.
|
||
@sc{Cvs} also supports mechanisms which facilitate
|
||
various kinds of communcation, without actually
|
||
enforcing rules like reserved checkouts do.
|
||
|
||
The rest of this chapter describes how these various
|
||
models work, and some of the issues involved in
|
||
choosing between them.
|
||
|
||
@ignore
|
||
Here is a draft reserved checkout design or discussion
|
||
of the issues. This seems like as good a place as any
|
||
for this.
|
||
|
||
Might want a cvs lock/cvs unlock--in which the names
|
||
differ from edit/unedit because the network must be up
|
||
for these to work. unedit gives an error if there is a
|
||
reserved checkout in place (so that people don't
|
||
accidentally leave locks around); unlock gives an error
|
||
if one is not in place (this is more arguable; perhaps
|
||
it should act like unedit in that case).
|
||
|
||
On the other hand, might want it so that emacs,
|
||
scripts, etc., can get ready to edit a file without
|
||
having to know which model is in use. In that case we
|
||
would have a "cvs watch lock" (or .cvsrc?) (that is,
|
||
three settings, "on", "off", and "lock"). Having cvs
|
||
watch lock set would cause a get to record in the CVS
|
||
directory which model is in use, and cause "cvs edit"
|
||
to change behaviors. We'd want a way to query which
|
||
setting is in effect (this would be handy even if it is
|
||
only "on" or "off" as presently). If lock is in
|
||
effect, then commit would require a lock before
|
||
allowing a checkin; chmod wouldn't suffice (might be
|
||
debatable--see chmod comment below, in watches--but it
|
||
is the way people expect RCS to work and I can't think
|
||
of any significant downside. On the other hand, maybe
|
||
it isn't worth bothering, because people who are used
|
||
to RCS wouldn't think to use chmod anyway).
|
||
|
||
Implementation: use file attributes or use RCS
|
||
locking. The former avoids more dependence on RCS
|
||
behaviors we will need to reimplement as we librarify
|
||
RCS, and makes it easier to import/export RCS files (in
|
||
that context, want to ignore the locker field). But
|
||
note that RCS locks are per-branch, which is the
|
||
correct behavior (this is also an issue for the "watch
|
||
on" features; they should be per-branch too).
|
||
|
||
Here are a few more random notes about implementation
|
||
details, assuming "cvs watch lock" and
|
||
|
||
CVS/Watched file? Or try to fit this into CVS/Entries somehow?
|
||
Cases: (1) file is checked out (unreserved or with watch on) by old
|
||
version of CVS, now we do something with new one, (2) file is checked
|
||
out by new version, now we do something with old one.
|
||
|
||
Remote protocol would have a "Watched" analogous to "Mode". Of course
|
||
it would apply to all Updated-like requests. How do we keep this
|
||
setting up to date? I guess that there wants to be a Watched request,
|
||
and the server would send a new one if it isn't up to date? (Ugh--hard
|
||
to implement and slows down "cvs -q update"--is there an easier way?)
|
||
|
||
"cvs edit"--checks CVS/Watched, and if watch lock, then sends
|
||
"edit-lock" request. Which comes back with a Checked-in with
|
||
appropriate Watched (off, on, lock, locked, or some such?), or error
|
||
message if already locked.
|
||
|
||
"cvs commit"--only will commit if off/on/locked. lock is not OK.
|
||
|
||
Doc:
|
||
note that "cvs edit" must be connected to network if watch lock is in
|
||
effect.
|
||
|
||
Talk about what to do if someone has locked a file and you want to
|
||
edit that file. (breaking locks, or lack thereof).
|
||
|
||
|
||
@end ignore
|
||
|
||
@menu
|
||
* File status:: A file can be in several states
|
||
* Updating a file:: Bringing a file up-to-date
|
||
* Conflicts example:: An informative example
|
||
* Informing others:: To cooperate you must inform
|
||
* Concurrency:: Simultaneous repository access
|
||
* Watches:: Mechanisms to track who is editing files
|
||
* Choosing a model:: Reserved or unreserved checkouts?
|
||
@end menu
|
||
|
||
@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
|
||
@node File status
|
||
@section File status
|
||
@cindex File status
|
||
@cindex Status of a file
|
||
|
||
@c Shouldn't this start with an example or something,
|
||
@c introducing the unreserved checkout model? Before we
|
||
@c dive into listing states?
|
||
Based on what operations you have performed on a
|
||
checked out file, and what operations others have
|
||
performed to that file in the repository, one can
|
||
classify a file in a number of states. The states, as
|
||
reported by the @code{status} command, are:
|
||
|
||
@c The order of items is chosen to group logically
|
||
@c similar outputs together.
|
||
@c People who want alphabetical can use the index...
|
||
@table @asis
|
||
@cindex Up-to-date
|
||
@item Up-to-date
|
||
The file is identical with the latest revision in the
|
||
repository for the branch in use.
|
||
@c FIXME: should we clarify "in use"? The answer is
|
||
@c sticky tags, and trying to distinguish branch sticky
|
||
@c tags from non-branch sticky tags seems rather awkward
|
||
@c here.
|
||
@c FIXME: What happens with non-branch sticky tags? Is
|
||
@c a stuck file "Up-to-date" or "Needs checkout" or what?
|
||
|
||
@item Locally Modified
|
||
@cindex Locally Modified
|
||
You have edited the file, and not yet committed your changes.
|
||
|
||
@item Locally Added
|
||
@cindex Locally Added
|
||
You have added the file with @code{add}, and not yet
|
||
committed your changes.
|
||
@c There are many cases involving the file being
|
||
@c added/removed/modified in the working directory, and
|
||
@c added/removed/modified in the repository, which we
|
||
@c don't try to describe here. I'm not sure that "cvs
|
||
@c status" produces a non-confusing output in most of
|
||
@c those cases.
|
||
|
||
@item Locally Removed
|
||
@cindex Locally Removed
|
||
You have removed the file with @code{remove}, and not yet
|
||
committed your changes.
|
||
|
||
@item Needs Checkout
|
||
@cindex Needs Checkout
|
||
Someone else has committed a newer revision to the
|
||
repository. The name is slightly misleading; you will
|
||
ordinarily use @code{update} rather than
|
||
@code{checkout} to get that newer revision.
|
||
|
||
@item Needs Patch
|
||
@cindex Needs Patch
|
||
@c See also newb-123j0 in sanity.sh (although that case
|
||
@c should probably be changed rather than documented).
|
||
Like Needs Checkout, but the @sc{cvs} server will send
|
||
a patch rather than the entire file. Sending a patch or
|
||
sending an entire file accomplishes the same thing.
|
||
|
||
@item Needs Merge
|
||
@cindex Needs Merge
|
||
Someone else has committed a newer revision to the repository, and you
|
||
have also made modifications to the file.
|
||
|
||
@item File had conflicts on merge
|
||
@cindex File had conflicts on merge
|
||
@c is it worth saying that this message was "Unresolved
|
||
@c Conflict" in CVS 1.9 and earlier? I'm inclined to
|
||
@c think that is unnecessarily confusing to new users.
|
||
This is like Locally Modified, except that a previous
|
||
@code{update} command gave a conflict. If you have not
|
||
already done so, you need to
|
||
resolve the conflict as described in @ref{Conflicts example}.
|
||
|
||
@item Unknown
|
||
@cindex Unknown
|
||
@sc{Cvs} doesn't know anything about this file. For
|
||
example, you have created a new file and have not run
|
||
@code{add}.
|
||
@c
|
||
@c "Entry Invalid" and "Classify Error" are also in the
|
||
@c status.c. The latter definitely indicates a CVS bug
|
||
@c (should it be worded more like "internal error" so
|
||
@c people submit bug reports if they see it?). The former
|
||
@c I'm not as sure; I haven't tracked down whether/when it
|
||
@c appears in "cvs status" output.
|
||
|
||
@end table
|
||
|
||
To help clarify the file status, @code{status} also
|
||
reports the @code{Working revision} which is the
|
||
revision that the file in the working directory derives
|
||
from, and the @code{Repository revision} which is the
|
||
latest revision in the repository for the branch in
|
||
use.
|
||
@c FIXME: should we clarify "in use"? The answer is
|
||
@c sticky tags, and trying to distinguish branch sticky
|
||
@c tags from non-branch sticky tags seems rather awkward
|
||
@c here.
|
||
@c FIXME: What happens with non-branch sticky tags?
|
||
@c What is the Repository Revision there? See the
|
||
@c comment at vn_rcs in cvs.h, which is kind of
|
||
@c confused--we really need to document better what this
|
||
@c field contains.
|
||
@c Q: Should we document "New file!" and other such
|
||
@c outputs or are they self-explanatory?
|
||
@c FIXME: what about the date to the right of "Working
|
||
@c revision"? It doesn't appear with client/server and
|
||
@c seems unnecessary (redundant with "ls -l") so
|
||
@c perhaps it should be removed for non-client/server too?
|
||
@c FIXME: Need some examples.
|
||
|
||
@c Would be nice to have an @example showing output
|
||
@c from cvs status, with comments showing the xref
|
||
@c where each part of the output is described. This
|
||
@c might fit in nicely if it is desirable to split this
|
||
@c node in two; one to introduce "cvs status" and one
|
||
@c to list each of the states.
|
||
The options to @code{status} are listed in
|
||
@ref{Invoking CVS}. For information on its @code{Sticky tag}
|
||
and @code{Sticky date} output, see @ref{Sticky tags}.
|
||
For information on its @code{Sticky options} output,
|
||
see the @samp{-k} option in @ref{update options}.
|
||
|
||
You can think of the @code{status} and @code{update}
|
||
commands as somewhat complementary. You use
|
||
@code{update} to bring your files up to date, and you
|
||
can use @code{status} to give you some idea of what an
|
||
@code{update} would do (of course, the state of the
|
||
repository might change before you actually run
|
||
@code{update}). In fact, if you want a command to
|
||
display file status in a more brief format than is
|
||
displayed by the @code{status} command, you can invoke
|
||
|
||
@cindex update, to display file status
|
||
@example
|
||
$ cvs -n -q update
|
||
@end example
|
||
|
||
The @samp{-n} option means to not actually do the
|
||
update, but merely to display statuses; the @samp{-q}
|
||
option avoids printing the name of each directory. For
|
||
more information on the @code{update} command, and
|
||
these options, see @ref{Invoking CVS}.
|
||
|
||
@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
|
||
@node Updating a file
|
||
@section Bringing a file up to date
|
||
@cindex Bringing a file up to date
|
||
@cindex Updating a file
|
||
@cindex Merging a file
|
||
@cindex update, introduction
|
||
|
||
When you want to update or merge a file, use the @code{update}
|
||
command. For files that are not up to date this is roughly equivalent
|
||
to a @code{checkout} command: the newest revision of the file is
|
||
extracted from the repository and put in your working copy of the
|
||
module.
|
||
|
||
Your modifications to a file are never lost when you
|
||
use @code{update}. If no newer revision exists,
|
||
running @code{update} has no effect. If you have
|
||
edited the file, and a newer revision is available,
|
||
@sc{cvs} will merge all changes into your working copy.
|
||
|
||
For instance, imagine that you checked out revision 1.4 and started
|
||
editing it. In the meantime someone else committed revision 1.5, and
|
||
shortly after that revision 1.6. If you run @code{update} on the file
|
||
now, @sc{cvs} will incorporate all changes between revision 1.4 and 1.6 into
|
||
your file.
|
||
|
||
@cindex Overlap
|
||
If any of the changes between 1.4 and 1.6 were made too
|
||
close to any of the changes you have made, an
|
||
@dfn{overlap} occurs. In such cases a warning is
|
||
printed, and the resulting file includes both
|
||
versions of the lines that overlap, delimited by
|
||
special markers.
|
||
@xref{update}, for a complete description of the
|
||
@code{update} command.
|
||
|
||
@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
|
||
@node Conflicts example
|
||
@section Conflicts example
|
||
@cindex Merge, an example
|
||
@cindex Example of merge
|
||
@cindex driver.c (merge example)
|
||
|
||
Suppose revision 1.4 of @file{driver.c} contains this:
|
||
|
||
@example
|
||
#include <stdio.h>
|
||
|
||
void main()
|
||
@{
|
||
parse();
|
||
if (nerr == 0)
|
||
gencode();
|
||
else
|
||
fprintf(stderr, "No code generated.\n");
|
||
exit(nerr == 0 ? 0 : 1);
|
||
@}
|
||
@end example
|
||
|
||
@noindent
|
||
Revision 1.6 of @file{driver.c} contains this:
|
||
|
||
@example
|
||
#include <stdio.h>
|
||
|
||
int main(int argc,
|
||
char **argv)
|
||
@{
|
||
parse();
|
||
if (argc != 1)
|
||
@{
|
||
fprintf(stderr, "tc: No args expected.\n");
|
||
exit(1);
|
||
@}
|
||
if (nerr == 0)
|
||
gencode();
|
||
else
|
||
fprintf(stderr, "No code generated.\n");
|
||
exit(!!nerr);
|
||
@}
|
||
@end example
|
||
|
||
@noindent
|
||
Your working copy of @file{driver.c}, based on revision
|
||
1.4, contains this before you run @samp{cvs update}:
|
||
@c -- Really include "cvs"?
|
||
|
||
@example
|
||
#include <stdlib.h>
|
||
#include <stdio.h>
|
||
|
||
void main()
|
||
@{
|
||
init_scanner();
|
||
parse();
|
||
if (nerr == 0)
|
||
gencode();
|
||
else
|
||
fprintf(stderr, "No code generated.\n");
|
||
exit(nerr == 0 ? EXIT_SUCCESS : EXIT_FAILURE);
|
||
@}
|
||
@end example
|
||
|
||
@noindent
|
||
You run @samp{cvs update}:
|
||
@c -- Really include "cvs"?
|
||
|
||
@example
|
||
$ cvs update driver.c
|
||
RCS file: /usr/local/cvsroot/yoyodyne/tc/driver.c,v
|
||
retrieving revision 1.4
|
||
retrieving revision 1.6
|
||
Merging differences between 1.4 and 1.6 into driver.c
|
||
rcsmerge warning: overlaps during merge
|
||
cvs update: conflicts found in driver.c
|
||
C driver.c
|
||
@end example
|
||
|
||
@noindent
|
||
@cindex Conflicts (merge example)
|
||
@sc{cvs} tells you that there were some conflicts.
|
||
Your original working file is saved unmodified in
|
||
@file{.#driver.c.1.4}. The new version of
|
||
@file{driver.c} contains this:
|
||
|
||
@example
|
||
#include <stdlib.h>
|
||
#include <stdio.h>
|
||
|
||
int main(int argc,
|
||
char **argv)
|
||
@{
|
||
init_scanner();
|
||
parse();
|
||
if (argc != 1)
|
||
@{
|
||
fprintf(stderr, "tc: No args expected.\n");
|
||
exit(1);
|
||
@}
|
||
if (nerr == 0)
|
||
gencode();
|
||
else
|
||
fprintf(stderr, "No code generated.\n");
|
||
@asis{}<<<<<<< driver.c
|
||
exit(nerr == 0 ? EXIT_SUCCESS : EXIT_FAILURE);
|
||
@asis{}=======
|
||
exit(!!nerr);
|
||
@asis{}>>>>>>> 1.6
|
||
@}
|
||
@end example
|
||
|
||
@noindent
|
||
@cindex Markers, conflict
|
||
@cindex Conflict markers
|
||
@cindex <<<<<<<
|
||
@cindex >>>>>>>
|
||
@cindex =======
|
||
|
||
Note how all non-overlapping modifications are incorporated in your working
|
||
copy, and that the overlapping section is clearly marked with
|
||
@samp{<<<<<<<}, @samp{=======} and @samp{>>>>>>>}.
|
||
|
||
@cindex Resolving a conflict
|
||
@cindex Conflict resolution
|
||
You resolve the conflict by editing the file, removing the markers and
|
||
the erroneous line. Suppose you end up with this file:
|
||
@c -- Add xref to the pcl-cvs manual when it talks
|
||
@c -- about this.
|
||
@example
|
||
#include <stdlib.h>
|
||
#include <stdio.h>
|
||
|
||
int main(int argc,
|
||
char **argv)
|
||
@{
|
||
init_scanner();
|
||
parse();
|
||
if (argc != 1)
|
||
@{
|
||
fprintf(stderr, "tc: No args expected.\n");
|
||
exit(1);
|
||
@}
|
||
if (nerr == 0)
|
||
gencode();
|
||
else
|
||
fprintf(stderr, "No code generated.\n");
|
||
exit(nerr == 0 ? EXIT_SUCCESS : EXIT_FAILURE);
|
||
@}
|
||
@end example
|
||
|
||
@noindent
|
||
You can now go ahead and commit this as revision 1.7.
|
||
|
||
@example
|
||
$ cvs commit -m "Initialize scanner. Use symbolic exit values." driver.c
|
||
Checking in driver.c;
|
||
/usr/local/cvsroot/yoyodyne/tc/driver.c,v <-- driver.c
|
||
new revision: 1.7; previous revision: 1.6
|
||
done
|
||
@end example
|
||
|
||
For your protection, @sc{cvs} will refuse to check in a
|
||
file if a conflict occurred and you have not resolved
|
||
the conflict. Currently to resolve a conflict, you
|
||
must change the timestamp on the file, and must also
|
||
insure that the file contains no conflict markers. If
|
||
your file legitimately contains conflict markers (that
|
||
is, occurrences of @samp{>>>>>>> } at the start of a
|
||
line that don't mark a conflict), then @sc{cvs} has
|
||
trouble handling this and you need to start hacking on
|
||
the @code{CVS/Entries} file or other such workarounds.
|
||
@c FIXME: There should be a "cvs resolved" command
|
||
@c which clears the conflict indication. For a nice user
|
||
@c interface, this should be invoked by an interactive
|
||
@c merge tool like emerge rather than by the user
|
||
@c directly--such a tool can verify that the user has
|
||
@c really dealt with each conflict.
|
||
|
||
@cindex emerge
|
||
If you use release 1.04 or later of pcl-cvs (a @sc{gnu}
|
||
Emacs front-end for @sc{cvs}) you can use an Emacs
|
||
package called emerge to help you resolve conflicts.
|
||
See the documentation for pcl-cvs.
|
||
|
||
@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
|
||
@node Informing others
|
||
@section Informing others about commits
|
||
@cindex Informing others
|
||
@cindex Spreading information
|
||
@cindex Mail, automatic mail on commit
|
||
|
||
It is often useful to inform others when you commit a
|
||
new revision of a file. The @samp{-i} option of the
|
||
@file{modules} file, or the @file{loginfo} file, can be
|
||
used to automate this process. @xref{modules}.
|
||
@xref{loginfo}. You can use these features of @sc{cvs}
|
||
to, for instance, instruct @sc{cvs} to mail a
|
||
message to all developers, or post a message to a local
|
||
newsgroup.
|
||
@c -- More text would be nice here.
|
||
|
||
@node Concurrency
|
||
@section Several developers simultaneously attempting to run CVS
|
||
|
||
@cindex locks, cvs
|
||
@c For a discussion of *why* CVS creates locks, see
|
||
@c the comment at the start of src/lock.c
|
||
If several developers try to run @sc{cvs} at the same
|
||
time, one may get the following message:
|
||
|
||
@example
|
||
[11:43:23] waiting for bach's lock in /usr/local/cvsroot/foo
|
||
@end example
|
||
|
||
@sc{cvs} will try again every 30 seconds, and either
|
||
continue with the operation or print the message again,
|
||
if it still needs to wait. If a lock seems to stick
|
||
around for an undue amount of time, find the person
|
||
holding the lock and ask them about the cvs command
|
||
they are running. If they aren't running a cvs
|
||
command, look in the repository directory mentioned in
|
||
the message and remove files which they own whose names
|
||
start with @file{#cvs.tfl}, @file{#cvs.rfl}, or
|
||
@file{#cvs.wfl}.
|
||
|
||
Note that these locks are to protect @sc{cvs}'s
|
||
internal data structures and have no relationship to
|
||
the word @dfn{lock} in the sense used by
|
||
@sc{rcs}---which refers to reserved checkouts
|
||
(@pxref{Multiple developers}).
|
||
|
||
Any number of people can be reading from a given
|
||
repository at a time; only when someone is writing do
|
||
the locks prevent other people from reading or writing.
|
||
|
||
@cindex Atomic transactions, lack of
|
||
@cindex Transactions, atomic, lack of
|
||
@c the following talks about what one might call commit/update
|
||
@c atomicity.
|
||
@c Probably also should say something about
|
||
@c commit/commit atomicity, that is, "An update will
|
||
@c not get partial versions of more than one commit".
|
||
@c CVS currently has this property and I guess we can
|
||
@c make it a documented feature.
|
||
@c For example one person commits
|
||
@c a/one.c and b/four.c and another commits a/two.c and
|
||
@c b/three.c. Then an update cannot get the new a/one.c
|
||
@c and a/two.c and the old b/four.c and b/three.c.
|
||
One might hope for the following property
|
||
|
||
@example
|
||
If someone commits some changes in one cvs command,
|
||
then an update by someone else will either get all the
|
||
changes, or none of them.
|
||
@end example
|
||
|
||
but @sc{cvs} does @emph{not} have this property. For
|
||
example, given the files
|
||
|
||
@example
|
||
a/one.c
|
||
a/two.c
|
||
b/three.c
|
||
b/four.c
|
||
@end example
|
||
|
||
if someone runs
|
||
|
||
@example
|
||
cvs ci a/two.c b/three.c
|
||
@end example
|
||
|
||
and someone else runs @code{cvs update} at the same
|
||
time, the person running @code{update} might get only
|
||
the change to @file{b/three.c} and not the change to
|
||
@file{a/two.c}.
|
||
|
||
@node Watches
|
||
@section Mechanisms to track who is editing files
|
||
@cindex Watches
|
||
|
||
For many groups, use of @sc{cvs} in its default mode is
|
||
perfectly satisfactory. Users may sometimes go to
|
||
check in a modification only to find that another
|
||
modification has intervened, but they deal with it and
|
||
proceed with their check in. Other groups prefer to be
|
||
able to know who is editing what files, so that if two
|
||
people try to edit the same file they can choose to
|
||
talk about who is doing what when rather than be
|
||
surprised at check in time. The features in this
|
||
section allow such coordination, while retaining the
|
||
ability of two developers to edit the same file at the
|
||
same time.
|
||
|
||
@c Some people might ask why CVS does not enforce the
|
||
@c rule on chmod, by requiring a cvs edit before a cvs
|
||
@c commit. The main reason is that it could always be
|
||
@c circumvented--one could edit the file, and
|
||
@c then when ready to check it in, do the cvs edit and put
|
||
@c in the new contents and do the cvs commit. One
|
||
@c implementation note: if we _do_ want to have cvs commit
|
||
@c require a cvs edit, we should store the state on
|
||
@c whether the cvs edit has occurred in the working
|
||
@c directory, rather than having the server try to keep
|
||
@c track of what working directories exist.
|
||
@c FIXME: should the above discussion be part of the
|
||
@c manual proper, somewhere, not just in a comment?
|
||
For maximum benefit developers should use @code{cvs
|
||
edit} (not @code{chmod}) to make files read-write to
|
||
edit them, and @code{cvs release} (not @code{rm}) to
|
||
discard a working directory which is no longer in use,
|
||
but @sc{cvs} is not able to enforce this behavior.
|
||
|
||
@c I'm a little dissatisfied with this presentation,
|
||
@c because "watch on"/"edit"/"editors" are one set of
|
||
@c functionality, and "watch add"/"watchers" is another
|
||
@c which is somewhat orthogonal even though they interact in
|
||
@c various ways. But I think it might be
|
||
@c confusing to describe them separately (e.g. "watch
|
||
@c add" with loginfo). I don't know.
|
||
|
||
@menu
|
||
* Setting a watch:: Telling CVS to watch certain files
|
||
* Getting Notified:: Telling CVS to notify you
|
||
* Editing files:: How to edit a file which is being watched
|
||
* Watch information:: Information about who is watching and editing
|
||
* Watches Compatibility:: Watches interact poorly with CVS 1.6 or earlier
|
||
@end menu
|
||
|
||
@node Setting a watch
|
||
@subsection Telling CVS to watch certain files
|
||
|
||
To enable the watch features, you first specify that
|
||
certain files are to be watched.
|
||
|
||
@cindex watch on (subcommand)
|
||
@deffn Command {cvs watch on} [@code{-lR}] files @dots{}
|
||
|
||
@cindex read-only files, and watches
|
||
Specify that developers should run @code{cvs edit}
|
||
before editing @var{files}. CVS will create working
|
||
copies of @var{files} read-only, to remind developers
|
||
to run the @code{cvs edit} command before working on
|
||
them.
|
||
|
||
If @var{files} includes the name of a directory, CVS
|
||
arranges to watch all files added to the corresponding
|
||
repository directory, and sets a default for files
|
||
added in the future; this allows the user to set
|
||
notification policies on a per-directory basis. The
|
||
contents of the directory are processed recursively,
|
||
unless the @code{-l} option is given.
|
||
The @code{-R} option can be used to force recursion if the @code{-l}
|
||
option is set in @file{~/.cvsrc} (@pxref{~/.cvsrc}).
|
||
|
||
If @var{files} is omitted, it defaults to the current directory.
|
||
|
||
@cindex watch off (subcommand)
|
||
@end deffn
|
||
|
||
@deffn Command {cvs watch off} [@code{-lR}] files @dots{}
|
||
|
||
Do not provide notification about work on @var{files}. CVS will create
|
||
working copies of @var{files} read-write.
|
||
|
||
The @var{files} and options are processed as for @code{cvs
|
||
watch on}.
|
||
|
||
@end deffn
|
||
|
||
@node Getting Notified
|
||
@subsection Telling CVS to notify you
|
||
|
||
You can tell @sc{cvs} that you want to receive
|
||
notifications about various actions taken on a file.
|
||
You can do this without using @code{cvs watch on} for
|
||
the file, but generally you will want to use @code{cvs
|
||
watch on}, so that developers use the @code{cvs edit}
|
||
command.
|
||
|
||
@cindex watch add (subcommand)
|
||
@deffn Command {cvs watch add} [@code{-a} action] [@code{-lR}] files @dots{}
|
||
|
||
Add the current user to the list of people to receive notification of
|
||
work done on @var{files}.
|
||
|
||
The @code{-a} option specifies what kinds of events CVS should notify
|
||
the user about. @var{action} is one of the following:
|
||
|
||
@table @code
|
||
|
||
@item edit
|
||
Another user has applied the @code{cvs edit} command (described
|
||
below) to a file.
|
||
|
||
@item unedit
|
||
Another user has applied the @code{cvs unedit} command (described
|
||
below) or the @code{cvs release} command to a file, or has deleted
|
||
the file and allowed @code{cvs update} to recreate it.
|
||
|
||
@item commit
|
||
Another user has committed changes to a file.
|
||
|
||
@item all
|
||
All of the above.
|
||
|
||
@item none
|
||
None of the above. (This is useful with @code{cvs edit},
|
||
described below.)
|
||
|
||
@end table
|
||
|
||
The @code{-a} option may appear more than once, or not at all. If
|
||
omitted, the action defaults to @code{all}.
|
||
|
||
The @var{files} and options are processed as for the
|
||
@code{cvs watch} commands.
|
||
|
||
@end deffn
|
||
|
||
|
||
@cindex watch remove (subcommand)
|
||
@deffn Command {cvs watch remove} [@code{-a} action] [@code{-lR}] files @dots{}
|
||
|
||
Remove a notification request established using @code{cvs watch add};
|
||
the arguments are the same. If the @code{-a} option is present, only
|
||
watches for the specified actions are removed.
|
||
|
||
@end deffn
|
||
|
||
@cindex notify (admin file)
|
||
When the conditions exist for notification, @sc{cvs}
|
||
calls the @file{notify} administrative file. Edit
|
||
@file{notify} as one edits the other administrative
|
||
files (@pxref{Intro administrative files}). This
|
||
file follows the usual conventions for administrative
|
||
files (@pxref{syntax}), where each line is a regular
|
||
expression followed by a command to execute. The
|
||
command should contain a single ocurrence of @samp{%s}
|
||
which will be replaced by the user to notify; the rest
|
||
of the information regarding the notification will be
|
||
supplied to the command on standard input. The
|
||
standard thing to put in the @code{notify} file is the
|
||
single line:
|
||
|
||
@example
|
||
ALL mail %s -s \"CVS notification\"
|
||
@end example
|
||
|
||
This causes users to be notified by electronic mail.
|
||
@c FIXME: should it be this hard to set up this
|
||
@c behavior (and the result when one fails to do so,
|
||
@c silent failure to notify, so non-obvious)? Should
|
||
@c CVS give a warning if no line in notify matches (and
|
||
@c document the use of "DEFAULT :" for the case where
|
||
@c skipping the notification is indeed desired)?
|
||
|
||
@cindex users (admin file)
|
||
Note that if you set this up in the straightforward
|
||
way, users receive notifications on the server machine.
|
||
One could of course write a @file{notify} script which
|
||
directed notifications elsewhere, but to make this
|
||
easy, @sc{cvs} allows you to associate a notification
|
||
address for each user. To do so create a file
|
||
@file{users} in @file{CVSROOT} with a line for each
|
||
user in the format @var{user}:@var{value}. Then
|
||
instead of passing the name of the user to be notified
|
||
to @file{notify}, @sc{cvs} will pass the @var{value}
|
||
(normally an email address on some other machine).
|
||
|
||
@sc{Cvs} does not notify you for your own changes.
|
||
Currently this check is done based on whether the user
|
||
name of the person taking the action which triggers
|
||
notification matches the user name of the person
|
||
getting notification. In fact, in general, the watches
|
||
features only track one edit by each user. It probably
|
||
would be more useful if watches tracked each working
|
||
directory separately, so this behavior might be worth
|
||
changing.
|
||
@c "behavior might be worth changing" is an effort to
|
||
@c point to future directions while also not promising
|
||
@c that "they" (as in "why don't they fix CVS to....")
|
||
@c will do this.
|
||
@c one implementation issue is identifying whether a
|
||
@c working directory is same or different. Comparing
|
||
@c pathnames/hostnames is hopeless, but having the server
|
||
@c supply a serial number which the client stores in the
|
||
@c CVS directory as a magic cookie should work.
|
||
|
||
@node Editing files
|
||
@subsection How to edit a file which is being watched
|
||
|
||
@cindex checkout, as term for getting ready to edit
|
||
Since a file which is being watched is checked out
|
||
read-only, you cannot simply edit it. To make it
|
||
read-write, and inform others that you are planning to
|
||
edit it, use the @code{cvs edit} command. Some systems
|
||
call this a @dfn{checkout}, but @sc{cvs} uses that term
|
||
for obtaining a copy of the sources (@pxref{Getting the
|
||
source}), an operation which those systems call a
|
||
@dfn{get} or a @dfn{fetch}.
|
||
@c Issue to think about: should we transition CVS
|
||
@c towards the "get" terminology? "cvs get" is already a
|
||
@c synonym for "cvs checkout" and that section of the
|
||
@c manual refers to "Getting the source". If this is
|
||
@c done, needs to be done gingerly (for example, we should
|
||
@c still accept "checkout" in .cvsrc files indefinitely
|
||
@c even if the CVS's messages are changed from "cvs checkout: "
|
||
@c to "cvs get: ").
|
||
@c There is a concern about whether "get" is not as
|
||
@c good for novices because it is a more general term
|
||
@c than "checkout" (and thus arguably harder to assign
|
||
@c a technical meaning for).
|
||
|
||
@cindex edit (subcommand)
|
||
@deffn Command {cvs edit} [options] files @dots{}
|
||
|
||
Prepare to edit the working files @var{files}. CVS makes the
|
||
@var{files} read-write, and notifies users who have requested
|
||
@code{edit} notification for any of @var{files}.
|
||
|
||
The @code{cvs edit} command accepts the same @var{options} as the
|
||
@code{cvs watch add} command, and establishes a temporary watch for the
|
||
user on @var{files}; CVS will remove the watch when @var{files} are
|
||
@code{unedit}ed or @code{commit}ted. If the user does not wish to
|
||
receive notifications, she should specify @code{-a none}.
|
||
|
||
The @var{files} and options are processed as for the @code{cvs
|
||
watch} commands.
|
||
|
||
@end deffn
|
||
|
||
Normally when you are done with a set of changes, you
|
||
use the @code{cvs commit} command, which checks in your
|
||
changes and returns the watched files to their usual
|
||
read-only state. But if you instead decide to abandon
|
||
your changes, or not to make any changes, you can use
|
||
the @code{cvs unedit} command.
|
||
|
||
@cindex unedit (subcommand)
|
||
@cindex abandoning work
|
||
@cindex reverting to repository version
|
||
@deffn Command {cvs unedit} [@code{-lR}] files @dots{}
|
||
|
||
Abandon work on the working files @var{files}, and revert them to the
|
||
repository versions on which they are based. CVS makes those
|
||
@var{files} read-only for which users have requested notification using
|
||
@code{cvs watch on}. CVS notifies users who have requested @code{unedit}
|
||
notification for any of @var{files}.
|
||
|
||
The @var{files} and options are processed as for the
|
||
@code{cvs watch} commands.
|
||
|
||
If watches are not in use, the @code{unedit} command
|
||
probably does not work, and the way to revert to the
|
||
repository version is to remove the file and then use
|
||
@code{cvs update} to get a new copy. The meaning is
|
||
not precisely the same; removing and updating may also
|
||
bring in some changes which have been made in the
|
||
repository since the last time you updated.
|
||
@c It would be a useful enhancement to CVS to make
|
||
@c unedit work in the non-watch case as well.
|
||
@end deffn
|
||
|
||
When using client/server @sc{cvs}, you can use the
|
||
@code{cvs edit} and @code{cvs unedit} commands even if
|
||
@sc{cvs} is unable to succesfully communicate with the
|
||
server; the notifications will be sent upon the next
|
||
successful @sc{cvs} command.
|
||
|
||
@node Watch information
|
||
@subsection Information about who is watching and editing
|
||
|
||
@cindex watchers (subcommand)
|
||
@deffn Command {cvs watchers} [@code{-lR}] files @dots{}
|
||
|
||
List the users currently watching changes to @var{files}. The report
|
||
includes the files being watched, and the mail address of each watcher.
|
||
|
||
The @var{files} and options are processed as for the
|
||
@code{cvs watch} commands.
|
||
|
||
@end deffn
|
||
|
||
|
||
@cindex editors (subcommand)
|
||
@deffn Command {cvs editors} [@code{-lR}] files @dots{}
|
||
|
||
List the users currently working on @var{files}. The report
|
||
includes the mail address of each user, the time when the user began
|
||
working with the file, and the host and path of the working directory
|
||
containing the file.
|
||
|
||
The @var{files} and options are processed as for the
|
||
@code{cvs watch} commands.
|
||
|
||
@end deffn
|
||
|
||
@node Watches Compatibility
|
||
@subsection Using watches with old versions of CVS
|
||
|
||
@cindex CVS 1.6, and watches
|
||
If you use the watch features on a repository, it
|
||
creates @file{CVS} directories in the repository and
|
||
stores the information about watches in that directory.
|
||
If you attempt to use @sc{cvs} 1.6 or earlier with the
|
||
repository, you get an error message such as the
|
||
following (all on one line):
|
||
|
||
@example
|
||
cvs update: cannot open CVS/Entries for reading:
|
||
No such file or directory
|
||
@end example
|
||
|
||
and your operation will likely be aborted. To use the
|
||
watch features, you must upgrade all copies of @sc{cvs}
|
||
which use that repository in local or server mode. If
|
||
you cannot upgrade, use the @code{watch off} and
|
||
@code{watch remove} commands to remove all watches, and
|
||
that will restore the repository to a state which
|
||
@sc{cvs} 1.6 can cope with.
|
||
|
||
@node Choosing a model
|
||
@section Choosing between reserved or unreserved checkouts
|
||
@cindex choosing, reserved or unreserved checkouts
|
||
|
||
Reserved and unreserved checkouts each have pros and
|
||
cons. Let it be said that a lot of this is a matter of
|
||
opinion or what works given different groups' working
|
||
styles, but here is a brief description of some of the
|
||
issues. There are many ways to organize a team of
|
||
developers. @sc{cvs} does not try to enforce a certain
|
||
organization. It is a tool that can be used in several
|
||
ways.
|
||
|
||
Reserved checkouts can be very counter-productive. If
|
||
two persons want to edit different parts of a file,
|
||
there may be no reason to prevent either of them from
|
||
doing so. Also, it is common for someone to take out a
|
||
lock on a file, because they are planning to edit it,
|
||
but then forget to release the lock.
|
||
|
||
@c "many groups"? specifics? cites to papers on this?
|
||
@c some way to weasel-word it a bit more so we don't
|
||
@c need facts :-)?
|
||
People, especially people who are familiar with
|
||
reserved checkouts, often wonder how often conflicts
|
||
occur if unreserved checkouts are used, and how
|
||
difficult they are to resolve. The experience with
|
||
many groups is that they occur rarely and usually are
|
||
relatively straightforward to resolve.
|
||
|
||
The rarity of serious conflicts may be surprising, until one realizes
|
||
that they occur only when two developers disagree on the proper design
|
||
for a given section of code; such a disagreement suggests that the
|
||
team has not been communicating properly in the first place. In order
|
||
to collaborate under @emph{any} source management regimen, developers
|
||
must agree on the general design of the system; given this agreement,
|
||
overlapping changes are usually straightforward to merge.
|
||
|
||
In some cases unreserved checkouts are clearly
|
||
inappropriate. If no merge tool exists for the kind of
|
||
file you are managing (for example word processor files
|
||
or files edited by Computer Aided Design programs), and
|
||
it is not desirable to change to a program which uses a
|
||
mergeable data format, then resolving conflicts is
|
||
going to be unpleasant enough that you generally will
|
||
be better off to simply avoid the conflicts instead, by
|
||
using reserved checkouts.
|
||
|
||
The watches features described above in @ref{Watches}
|
||
can be considered to be an intermediate model between
|
||
reserved checkouts and unreserved checkouts. When you
|
||
go to edit a file, it is possible to find out who else
|
||
is editing it. And rather than having the system
|
||
simply forbid both people editing the file, it can tell
|
||
you what the situation is and let you figure out
|
||
whether it is a problem in that particular case or not.
|
||
Therefore, for some groups it can be considered the
|
||
best of both the reserved checkout and unreserved
|
||
checkout worlds.
|
||
|
||
@c ---------------------------------------------------------------------
|
||
@node Revisions and branches
|
||
@chapter Revisions and branches
|
||
@cindex Branches
|
||
@cindex Main trunk and branches
|
||
@cindex Revision tree, making branches
|
||
|
||
For many uses of @sc{cvs}, one doesn't need to worry
|
||
too much about revision numbers; @sc{cvs} assigns
|
||
numbers such as @code{1.1}, @code{1.2}, and so on, and
|
||
that is all one needs to know. However, some people
|
||
prefer to have more knowledge and control concerning
|
||
how @sc{cvs} assigns revision numbers.
|
||
|
||
If one wants to keep track of a set of revisions
|
||
involving more than one file, such as which revisions
|
||
went into a particular release, one uses a @dfn{tag},
|
||
which is a symbolic revision which can be assigned to a
|
||
numeric revision in each file.
|
||
|
||
Another useful feature, especially when maintaining
|
||
several releases of a software product at once, is the
|
||
ability to make branches on the revision tree.
|
||
@c FIXME: probably want another sentence or two, very
|
||
@c briefly motivating branches.
|
||
|
||
@menu
|
||
* Revision numbers:: The meaning of a revision number
|
||
* Versions revisions releases:: Terminology used in this manual
|
||
* Assigning revisions:: Assigning revisions
|
||
* Tags:: Tags--Symbolic revisions
|
||
* Branches motivation:: What branches are good for
|
||
* Creating a branch:: Creating a branch
|
||
* Sticky tags:: Sticky tags
|
||
* Magic branch numbers:: Magic branch numbers
|
||
@end menu
|
||
|
||
@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
|
||
@node Revision numbers
|
||
@section Revision numbers
|
||
@cindex Revision numbers
|
||
@cindex Revision tree
|
||
@cindex Linear development
|
||
@cindex Number, revision-
|
||
@cindex Decimal revision number
|
||
@cindex Branch number
|
||
@cindex Number, branch
|
||
|
||
Each version of a file has a unique @dfn{revision
|
||
number}. Revision numbers look like @samp{1.1},
|
||
@samp{1.2}, @samp{1.3.2.2} or even @samp{1.3.2.2.4.5}.
|
||
A revision number always has an even number of
|
||
period-separated decimal integers. By default revision
|
||
1.1 is the first revision of a file. Each successive
|
||
revision is given a new number by increasing the
|
||
rightmost number by one. The following figure displays
|
||
a few revisions, with newer revisions to the right.
|
||
|
||
@example
|
||
+-----+ +-----+ +-----+ +-----+ +-----+
|
||
! 1.1 !----! 1.2 !----! 1.3 !----! 1.4 !----! 1.5 !
|
||
+-----+ +-----+ +-----+ +-----+ +-----+
|
||
@end example
|
||
|
||
@c Probably should move the following down a few
|
||
@c sections, until after "branch motivation".
|
||
@sc{cvs} is not limited to linear development. The
|
||
@dfn{revision tree} can be split into @dfn{branches},
|
||
where each branch is a self-maintained line of
|
||
development. Changes made on one branch can easily be
|
||
moved back to the main trunk.
|
||
|
||
Each branch has a @dfn{branch number}, consisting of an
|
||
odd number of period-separated decimal integers. The
|
||
branch number is created by appending an integer to the
|
||
revision number where the corresponding branch forked
|
||
off. Having branch numbers allows more than one branch
|
||
to be forked off from a certain revision.
|
||
|
||
@need 3500
|
||
All revisions on a branch have revision numbers formed
|
||
by appending an ordinal number to the branch number.
|
||
The following figure illustrates branching with an
|
||
example.
|
||
|
||
@example
|
||
@group
|
||
+-------------+
|
||
Branch 1.2.2.3.2 -> ! 1.2.2.3.2.1 !
|
||
/ +-------------+
|
||
/
|
||
/
|
||
+---------+ +---------+ +---------+
|
||
Branch 1.2.2 -> _! 1.2.2.1 !----! 1.2.2.2 !----! 1.2.2.3 !
|
||
/ +---------+ +---------+ +---------+
|
||
/
|
||
/
|
||
+-----+ +-----+ +-----+ +-----+ +-----+
|
||
! 1.1 !----! 1.2 !----! 1.3 !----! 1.4 !----! 1.5 ! <- The main trunk
|
||
+-----+ +-----+ +-----+ +-----+ +-----+
|
||
!
|
||
!
|
||
! +---------+ +---------+ +---------+
|
||
Branch 1.2.4 -> +---! 1.2.4.1 !----! 1.2.4.2 !----! 1.2.4.3 !
|
||
+---------+ +---------+ +---------+
|
||
|
||
@end group
|
||
@end example
|
||
|
||
@c -- However, at least for me the figure is not enough. I suggest more
|
||
@c -- text to accompany it. "A picture is worth a thousand words", so you
|
||
@c -- have to make sure the reader notices the couple of hundred words
|
||
@c -- *you* had in mind more than the others!
|
||
|
||
@c -- Why an even number of segments? This section implies that this is
|
||
@c -- how the main trunk is distinguished from branch roots, but you never
|
||
@c -- explicitly say that this is the purpose of the [by itself rather
|
||
@c -- surprising] restriction to an even number of segments.
|
||
|
||
The exact details of how the branch number is
|
||
constructed is not something you normally need to be
|
||
concerned about, but here is how it works: When
|
||
@sc{cvs} creates a branch number it picks the first
|
||
unused even integer, starting with 2. So when you want
|
||
to create a branch from revision 6.4 it will be
|
||
numbered 6.4.2. All branch numbers ending in a zero
|
||
(such as 6.4.0) are used internally by @sc{cvs}
|
||
(@pxref{Magic branch numbers}). The branch 1.1.1 has a
|
||
special meaning. @xref{Tracking sources}.
|
||
|
||
@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
|
||
@node Versions revisions releases
|
||
@section Versions, revisions and releases
|
||
@cindex Revisions, versions and releases
|
||
@cindex Versions, revisions and releases
|
||
@cindex Releases, revisions and versions
|
||
|
||
A file can have several versions, as described above.
|
||
Likewise, a software product can have several versions.
|
||
A software product is often given a version number such
|
||
as @samp{4.1.1}.
|
||
|
||
Versions in the first sense are called @dfn{revisions}
|
||
in this document, and versions in the second sense are
|
||
called @dfn{releases}. To avoid confusion, the word
|
||
@dfn{version} is almost never used in this document.
|
||
|
||
@node Assigning revisions
|
||
@section Assigning revisions
|
||
|
||
@c We avoid the "major revision" terminology. It seems
|
||
@c like jargon. Hopefully "first number" is clear enough.
|
||
By default, @sc{cvs} will assign numeric revisions by
|
||
leaving the first number the same and incrementing the
|
||
second number. For example, @code{1.1}, @code{1.2},
|
||
@code{1.3}, etc.
|
||
|
||
When adding a new file, the second number will always
|
||
be one and the first number will equal the highest
|
||
first number of any file in that directory. For
|
||
example, the current directory contains files whose
|
||
highest numbered revisions are @code{1.7}, @code{3.1},
|
||
and @code{4.12}, then an added file will be given the
|
||
numeric revision @code{4.1}.
|
||
|
||
@c This is sort of redundant with something we said a
|
||
@c while ago. Somewhere we need a better way of
|
||
@c introducing how the first number can be anything
|
||
@c except "1", perhaps. Also I don't think this
|
||
@c presentation is clear on why we are discussing releases
|
||
@c and first numbers of numeric revisions in the same
|
||
@c breath.
|
||
Normally there is no reason to care
|
||
about the revision numbers---it is easier to treat them
|
||
as internal numbers that @sc{cvs} maintains, and tags
|
||
provide a better way to distinguish between things like
|
||
release 1 versus release 2 of your product
|
||
(@pxref{Tags}). However, if you want to set the
|
||
numeric revisions, the @samp{-r} option to @code{cvs
|
||
commit} can do that. The @samp{-r} option implies the
|
||
@samp{-f} option, in the sense that it causes the
|
||
files to be committed even if they are not modified.
|
||
|
||
For example, to bring all your files up to
|
||
revision 3.0 (including those that haven't changed),
|
||
you might invoke:
|
||
|
||
@example
|
||
$ cvs commit -r 3.0
|
||
@end example
|
||
|
||
Note that the number you specify with @samp{-r} must be
|
||
larger than any existing revision number. That is, if
|
||
revision 3.0 exists, you cannot @samp{cvs commit
|
||
-r 1.3}. If you want to maintain several releases in
|
||
parallel, you need to use a branch (@pxref{Revisions and branches}).
|
||
|
||
@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
|
||
@node Tags
|
||
@section Tags--Symbolic revisions
|
||
@cindex Tags
|
||
|
||
The revision numbers live a life of their own. They
|
||
need not have anything at all to do with the release
|
||
numbers of your software product. Depending
|
||
on how you use @sc{cvs} the revision numbers might change several times
|
||
between two releases. As an example, some of the
|
||
source files that make up @sc{rcs} 5.6 have the following
|
||
revision numbers:
|
||
@cindex RCS revision numbers
|
||
|
||
@example
|
||
ci.c 5.21
|
||
co.c 5.9
|
||
ident.c 5.3
|
||
rcs.c 5.12
|
||
rcsbase.h 5.11
|
||
rcsdiff.c 5.10
|
||
rcsedit.c 5.11
|
||
rcsfcmp.c 5.9
|
||
rcsgen.c 5.10
|
||
rcslex.c 5.11
|
||
rcsmap.c 5.2
|
||
rcsutil.c 5.10
|
||
@end example
|
||
|
||
@cindex tag, command, introduction
|
||
@cindex Tag, symbolic name
|
||
@cindex Symbolic name (tag)
|
||
@cindex Name, symbolic (tag)
|
||
You can use the @code{tag} command to give a symbolic name to a
|
||
certain revision of a file. You can use the @samp{-v} flag to the
|
||
@code{status} command to see all tags that a file has, and
|
||
which revision numbers they represent. Tag names must
|
||
start with an uppercase or lowercase letter and can
|
||
contain uppercase and lowercase letters, digits,
|
||
@samp{-}, and @samp{_}. The two tag names @code{BASE}
|
||
and @code{HEAD} are reserved for use by @sc{cvs}. It
|
||
is expected that future names which are special to
|
||
@sc{cvs} will be specially named, for example by
|
||
starting with @samp{.}, rather than being named analogously to
|
||
@code{BASE} and @code{HEAD}, to avoid conflicts with
|
||
actual tag names.
|
||
@c Including a character such as % or = has also been
|
||
@c suggested as the naming convention for future
|
||
@c special tag names. Starting with . is nice because
|
||
@c that is not a legal tag name as far as RCS is concerned.
|
||
@c FIXME: CVS actually accepts quite a few characters
|
||
@c in tag names, not just the ones documented above
|
||
@c (see RCS_check_tag). RCS
|
||
@c defines legitimate tag names by listing illegal
|
||
@c characters rather than legal ones. CVS is said to lose its
|
||
@c mind if you try to use "/" (try making such a tag sticky
|
||
@c and using "cvs status" client/server--see remote
|
||
@c protocol format for entries line for probable cause).
|
||
@c TODO: The testsuite
|
||
@c should test for whatever are documented above as
|
||
@c officially-OK tag names, and CVS should at least reject
|
||
@c characters that won't work, like "/".
|
||
|
||
You'll want to choose some convention for naming tags,
|
||
based on information such as the name of the program
|
||
and the version number of the release. For example,
|
||
one might take the name of the program, immediately
|
||
followed by the version number with @samp{.} changed to
|
||
@samp{-}, so that CVS 1.9 would be tagged with the name
|
||
@code{cvs1-9}. If you choose a consistent convention,
|
||
then you won't constantly be guessing whether a tag is
|
||
@code{cvs-1-9} or @code{cvs1_9} or what. You might
|
||
even want to consider enforcing your convention in the
|
||
taginfo file (@pxref{user-defined logging}).
|
||
@c Might be nice to say more about using taginfo this
|
||
@c way, like giving an example, or pointing out any particular
|
||
@c issues which arise.
|
||
|
||
@cindex Adding a tag
|
||
@cindex tag, example
|
||
The following example shows how you can add a tag to a
|
||
file. The commands must be issued inside your working
|
||
copy of the module. That is, you should issue the
|
||
command in the directory where @file{backend.c}
|
||
resides.
|
||
|
||
@example
|
||
$ cvs tag release-0-4 backend.c
|
||
T backend.c
|
||
$ cvs status -v backend.c
|
||
===================================================================
|
||
File: backend.c Status: Up-to-date
|
||
|
||
Version: 1.4 Tue Dec 1 14:39:01 1992
|
||
RCS Version: 1.4 /u/cvsroot/yoyodyne/tc/backend.c,v
|
||
Sticky Tag: (none)
|
||
Sticky Date: (none)
|
||
Sticky Options: (none)
|
||
|
||
Existing Tags:
|
||
release-0-4 (revision: 1.4)
|
||
|
||
@end example
|
||
|
||
There is seldom reason to tag a file in isolation. A more common use is
|
||
to tag all the files that constitute a module with the same tag at
|
||
strategic points in the development life-cycle, such as when a release
|
||
is made.
|
||
|
||
@example
|
||
$ cvs tag release-1-0 .
|
||
cvs tag: Tagging .
|
||
T Makefile
|
||
T backend.c
|
||
T driver.c
|
||
T frontend.c
|
||
T parser.c
|
||
@end example
|
||
|
||
(When you give @sc{cvs} a directory as argument, it generally applies the
|
||
operation to all the files in that directory, and (recursively), to any
|
||
subdirectories that it may contain. @xref{Recursive behavior}.)
|
||
|
||
@cindex Retrieving an old revision using tags
|
||
@cindex Tag, retrieving old revisions
|
||
The @code{checkout} command has a flag, @samp{-r}, that lets you check out
|
||
a certain revision of a module. This flag makes it easy to
|
||
retrieve the sources that make up release 1.0 of the module @samp{tc} at
|
||
any time in the future:
|
||
|
||
@example
|
||
$ cvs checkout -r release-1-0 tc
|
||
@end example
|
||
|
||
@noindent
|
||
This is useful, for instance, if someone claims that there is a bug in
|
||
that release, but you cannot find the bug in the current working copy.
|
||
|
||
You can also check out a module as it was at any given date.
|
||
@xref{checkout options}.
|
||
|
||
When you tag more than one file with the same tag you
|
||
can think about the tag as "a curve drawn through a
|
||
matrix of filename vs. revision number." Say we have 5
|
||
files with the following revisions:
|
||
|
||
@example
|
||
@group
|
||
file1 file2 file3 file4 file5
|
||
|
||
1.1 1.1 1.1 1.1 /--1.1* <-*- TAG
|
||
1.2*- 1.2 1.2 -1.2*-
|
||
1.3 \- 1.3*- 1.3 / 1.3
|
||
1.4 \ 1.4 / 1.4
|
||
\-1.5*- 1.5
|
||
1.6
|
||
@end group
|
||
@end example
|
||
|
||
At some time in the past, the @code{*} versions were tagged.
|
||
You can think of the tag as a handle attached to the curve
|
||
drawn through the tagged revisions. When you pull on
|
||
the handle, you get all the tagged revisions. Another
|
||
way to look at it is that you "sight" through a set of
|
||
revisions that is "flat" along the tagged revisions,
|
||
like this:
|
||
|
||
@example
|
||
@group
|
||
file1 file2 file3 file4 file5
|
||
|
||
1.1
|
||
1.2
|
||
1.1 1.3 _
|
||
1.1 1.2 1.4 1.1 /
|
||
1.2*----1.3*----1.5*----1.2*----1.1 (--- <--- Look here
|
||
1.3 1.6 1.3 \_
|
||
1.4 1.4
|
||
1.5
|
||
@end group
|
||
@end example
|
||
|
||
@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
|
||
@node Branches motivation
|
||
@section What branches are good for
|
||
@cindex Branches motivation
|
||
@cindex What branches are good for
|
||
@cindex Motivation for branches
|
||
|
||
Suppose that release 1.0 of tc has been made. You are continuing to
|
||
develop tc, planning to create release 1.1 in a couple of months. After a
|
||
while your customers start to complain about a fatal bug. You check
|
||
out release 1.0 (@pxref{Tags}) and find the bug
|
||
(which turns out to have a trivial fix). However, the current revision
|
||
of the sources are in a state of flux and are not expected to be stable
|
||
for at least another month. There is no way to make a
|
||
bugfix release based on the newest sources.
|
||
|
||
The thing to do in a situation like this is to create a @dfn{branch} on
|
||
the revision trees for all the files that make up
|
||
release 1.0 of tc. You can then make
|
||
modifications to the branch without disturbing the main trunk. When the
|
||
modifications are finished you can select to either incorporate them on
|
||
the main trunk, or leave them on the branch.
|
||
|
||
@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
|
||
@node Creating a branch
|
||
@section Creating a branch
|
||
@cindex Creating a branch
|
||
@cindex Branch, creating a
|
||
@cindex rtag, creating a branch using
|
||
|
||
@c FIXME: should be more explicit about the value of
|
||
@c having a tag on the branchpoint. Also should talk
|
||
@c about creating a branch with tag not rtag.
|
||
The @code{rtag} command can be used to create a branch.
|
||
The @code{rtag} command is much like @code{tag}, but it
|
||
does not require that you have a working copy of the
|
||
module. @xref{rtag}. (You can also use the @code{tag}
|
||
command; @pxref{tag}).
|
||
|
||
@c Why does this example use -r? That seems like a
|
||
@c confusing thing to do in an example where we are
|
||
@c introducing branches. One user thought it was
|
||
@c a mandatory part of creating a branch for example.
|
||
@c And we are not sufficiently
|
||
@c "step by step" in terms of explaining
|
||
@c what argument one should give to -r.
|
||
@example
|
||
$ cvs rtag -b -r release-1-0 release-1-0-patches tc
|
||
@end example
|
||
|
||
The @samp{-b} flag makes @code{rtag} create a branch
|
||
(rather than just a symbolic revision name). @samp{-r
|
||
release-1-0} says that this branch should be rooted at the node (in
|
||
the revision tree) that corresponds to the tag
|
||
@samp{release-1-0}. Note that the numeric revision number that matches
|
||
@samp{release-1-0} will probably be different from file to file. The
|
||
name of the new branch is @samp{release-1-0-patches}, and the
|
||
module affected is @samp{tc}.
|
||
|
||
To fix the problem in release 1.0, you need a working
|
||
copy of the branch you just created.
|
||
|
||
@example
|
||
$ cvs checkout -r release-1-0-patches tc
|
||
$ cvs status -v driver.c backend.c
|
||
===================================================================
|
||
File: driver.c Status: Up-to-date
|
||
|
||
Version: 1.7 Sat Dec 5 18:25:54 1992
|
||
RCS Version: 1.7 /u/cvsroot/yoyodyne/tc/driver.c,v
|
||
Sticky Tag: release-1-0-patches (branch: 1.7.2)
|
||
Sticky Date: (none)
|
||
Sticky Options: (none)
|
||
|
||
Existing Tags:
|
||
release-1-0-patches (branch: 1.7.2)
|
||
release-1-0 (revision: 1.7)
|
||
|
||
===================================================================
|
||
File: backend.c Status: Up-to-date
|
||
|
||
Version: 1.4 Tue Dec 1 14:39:01 1992
|
||
RCS Version: 1.4 /u/cvsroot/yoyodyne/tc/backend.c,v
|
||
Sticky Tag: release-1-0-patches (branch: 1.4.2)
|
||
Sticky Date: (none)
|
||
Sticky Options: (none)
|
||
|
||
Existing Tags:
|
||
release-1-0-patches (branch: 1.4.2)
|
||
release-1-0 (revision: 1.4)
|
||
release-0-4 (revision: 1.4)
|
||
|
||
@end example
|
||
|
||
@cindex Branch numbers
|
||
As the output from the @code{status} command shows the branch
|
||
number is created by adding a digit at the tail of the revision number
|
||
it is based on. (If @samp{release-1-0} corresponds to revision 1.4, the
|
||
branch's revision number will be 1.4.2. For obscure reasons @sc{cvs} always
|
||
gives branches even numbers, starting at 2.
|
||
@xref{Revision numbers}.).
|
||
|
||
@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
|
||
@node Sticky tags
|
||
@section Sticky tags
|
||
@cindex Sticky tags
|
||
@cindex Tags, sticky
|
||
@cindex Branches, sticky
|
||
|
||
@c FIXME: make this stand alone better; many places
|
||
@c @xref to this node.
|
||
The @samp{-r release-1-0-patches} flag that was given
|
||
to @code{checkout} in the previous example
|
||
is @dfn{sticky}, that is, it will apply to subsequent commands
|
||
in this directory. If you commit any modifications, they are
|
||
committed on the branch. You can later merge the modifications into
|
||
the main trunk. @xref{Merging}.
|
||
|
||
You can use the @code{status} command to see what
|
||
sticky tags or dates are set:
|
||
|
||
@c FIXME: This example needs to stand alone better and it
|
||
@c would also better if it didn't use -v which only
|
||
@c clutters the output in this context.
|
||
@example
|
||
$ vi driver.c # @r{Fix the bugs}
|
||
$ cvs commit -m "Fixed initialization bug" driver.c
|
||
Checking in driver.c;
|
||
/usr/local/cvsroot/yoyodyne/tc/driver.c,v <-- driver.c
|
||
new revision: 1.7.2.1; previous revision: 1.7
|
||
done
|
||
$ cvs status -v driver.c
|
||
===================================================================
|
||
File: driver.c Status: Up-to-date
|
||
|
||
Version: 1.7.2.1 Sat Dec 5 19:35:03 1992
|
||
RCS Version: 1.7.2.1 /u/cvsroot/yoyodyne/tc/driver.c,v
|
||
Sticky Tag: release-1-0-patches (branch: 1.7.2)
|
||
Sticky Date: (none)
|
||
Sticky Options: (none)
|
||
|
||
Existing Tags:
|
||
release-1-0-patches (branch: 1.7.2)
|
||
release-1-0 (revision: 1.7)
|
||
|
||
@end example
|
||
|
||
@cindex Resetting sticky tags
|
||
@cindex Sticky tags, resetting
|
||
@cindex Deleting sticky tags
|
||
The sticky tags will remain on your working files until
|
||
you delete them with @samp{cvs update -A}. The
|
||
@samp{-A} option retrieves the version of the file from
|
||
the head of the trunk, and forgets any sticky tags,
|
||
dates, or options.
|
||
|
||
@cindex sticky date
|
||
Sticky tags are not just for branches. For example,
|
||
suppose that you want to avoid updating your working
|
||
directory, to isolate yourself from possibly
|
||
destabilizing changes other people are making. You
|
||
can, of course, just refrain from running @code{cvs
|
||
update}. But if you want to avoid updating only a
|
||
portion of a larger tree, then sticky tags can help.
|
||
If you check out a certain revision (such as 1.4) it
|
||
will become sticky. Subsequent @code{cvs update} will
|
||
not retrieve the latest revision until you reset the
|
||
tag with @code{cvs update -A}. Likewise, use of the
|
||
@samp{-D} option to @code{update} or @code{checkout}
|
||
sets a @dfn{sticky date}, which, similarly, causes that
|
||
date to be used for future retrievals.
|
||
|
||
@cindex Restoring old version of removed file
|
||
@cindex Resurrecting old version of dead file
|
||
Many times you will want to retrieve an old version of
|
||
a file without setting a sticky tag. The way to do
|
||
that is with the @samp{-p} option to @code{checkout} or
|
||
@code{update}, which sends the contents of the file to
|
||
standard output. For example, suppose you have a file
|
||
named @file{file1} which existed as revision 1.1, and
|
||
you then removed it (thus adding a dead revision 1.2).
|
||
Now suppose you want to add it again, with the same
|
||
contents it had previously. Here is how to do it:
|
||
|
||
@example
|
||
$ cvs update -p -r 1.1 file1 >file1
|
||
===================================================================
|
||
Checking out file1
|
||
RCS: /tmp/cvs-sanity/cvsroot/first-dir/Attic/file1,v
|
||
VERS: 1.1
|
||
***************
|
||
$ cvs add file1
|
||
cvs add: re-adding file file1 (in place of dead revision 1.2)
|
||
cvs add: use 'cvs commit' to add this file permanently
|
||
$ cvs commit -m test
|
||
Checking in file1;
|
||
/tmp/cvs-sanity/cvsroot/first-dir/file1,v <-- file1
|
||
new revision: 1.3; previous revision: 1.2
|
||
done
|
||
$
|
||
@end example
|
||
|
||
@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
|
||
@node Magic branch numbers
|
||
@section Magic branch numbers
|
||
|
||
@c Want xref to here from "log" and "admin"?
|
||
|
||
This section describes a @sc{cvs} feature called
|
||
@dfn{magic branches}. For most purposes, you need not
|
||
worry about magic branches; @sc{cvs} handles them for
|
||
you. However, they are visible to you in certain
|
||
circumstances, so it may be useful to have some idea of
|
||
how it works.
|
||
|
||
Externally, branch numbers consist of an odd number of
|
||
dot-separated decimal integers. @xref{Revision
|
||
numbers}. That is not the whole truth, however. For
|
||
efficiency reasons @sc{cvs} sometimes inserts an extra 0
|
||
in the second rightmost position (1.2.3 becomes
|
||
1.2.0.3, 8.9.10.11.12 becomes 8.9.10.11.0.12 and so
|
||
on).
|
||
|
||
@sc{cvs} does a pretty good job at hiding these so
|
||
called magic branches, but in a few places the hiding
|
||
is incomplete:
|
||
|
||
@itemize @bullet
|
||
@ignore
|
||
@c This is in ignore as I'm taking their word for it,
|
||
@c that this was fixed
|
||
@c a long time ago. But before deleting this
|
||
@c entirely, I'd rather verify it (and add a test
|
||
@c case to the testsuite).
|
||
@item
|
||
The magic branch can appear in the output from
|
||
@code{cvs status} in vanilla @sc{cvs} 1.3. This is
|
||
fixed in @sc{cvs} 1.3-s2.
|
||
|
||
@end ignore
|
||
@item
|
||
The magic branch number appears in the output from
|
||
@code{cvs log}.
|
||
@c What output should appear instead?
|
||
|
||
@item
|
||
You cannot specify a symbolic branch name to @code{cvs
|
||
admin}.
|
||
|
||
@end itemize
|
||
|
||
@c Can CVS do this automatically the first time
|
||
@c you check something in to that branch? Should
|
||
@c it?
|
||
You can use the @code{admin} command to reassign a
|
||
symbolic name to a branch the way @sc{rcs} expects it
|
||
to be. If @code{R4patches} is assigned to the branch
|
||
1.4.2 (magic branch number 1.4.0.2) in file
|
||
@file{numbers.c} you can do this:
|
||
|
||
@example
|
||
$ cvs admin -NR4patches:1.4.2 numbers.c
|
||
@end example
|
||
|
||
It only works if at least one revision is already
|
||
committed on the branch. Be very careful so that you
|
||
do not assign the tag to the wrong number. (There is
|
||
no way to see how the tag was assigned yesterday).
|
||
|
||
@c ---------------------------------------------------------------------
|
||
@node Merging
|
||
@chapter Merging
|
||
@cindex Merging
|
||
@cindex Copying changes
|
||
@cindex Branches, copying changes between
|
||
@cindex Changes, copying between branches
|
||
@cindex Modifications, copying between branches
|
||
|
||
You can include the changes made between any two
|
||
revisions into your working copy, by @dfn{merging}.
|
||
You can then commit that revision, and thus effectively
|
||
copy the changes onto another branch.
|
||
|
||
@menu
|
||
* Merging a branch:: Merging an entire branch
|
||
* Merging more than once:: Merging from a branch several times
|
||
* Merging two revisions:: Merging differences between two revisions
|
||
* Merging adds and removals:: What if files are added or removed?
|
||
@end menu
|
||
|
||
@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
|
||
@node Merging a branch
|
||
@section Merging an entire branch
|
||
@cindex Merging a branch
|
||
@cindex -j (merging branches)
|
||
|
||
You can merge changes made on a branch into your working copy by giving
|
||
the @samp{-j @var{branch}} flag to the @code{update} command. With one
|
||
@samp{-j @var{branch}} option it merges the changes made between the
|
||
point where the branch forked and newest revision on that branch (into
|
||
your working copy).
|
||
|
||
@cindex Join
|
||
The @samp{-j} stands for ``join''.
|
||
|
||
@cindex Branch merge example
|
||
@cindex Example, branch merge
|
||
@cindex Merge, branch example
|
||
Consider this revision tree:
|
||
|
||
@example
|
||
+-----+ +-----+ +-----+ +-----+
|
||
! 1.1 !----! 1.2 !----! 1.3 !----! 1.4 ! <- The main trunk
|
||
+-----+ +-----+ +-----+ +-----+
|
||
!
|
||
!
|
||
! +---------+ +---------+
|
||
Branch R1fix -> +---! 1.2.2.1 !----! 1.2.2.2 !
|
||
+---------+ +---------+
|
||
@end example
|
||
|
||
@noindent
|
||
The branch 1.2.2 has been given the tag (symbolic name) @samp{R1fix}. The
|
||
following example assumes that the module @samp{mod} contains only one
|
||
file, @file{m.c}.
|
||
|
||
@example
|
||
$ cvs checkout mod # @r{Retrieve the latest revision, 1.4}
|
||
|
||
$ cvs update -j R1fix m.c # @r{Merge all changes made on the branch,}
|
||
# @r{i.e. the changes between revision 1.2}
|
||
# @r{and 1.2.2.2, into your working copy}
|
||
# @r{of the file.}
|
||
|
||
$ cvs commit -m "Included R1fix" # @r{Create revision 1.5.}
|
||
@end example
|
||
|
||
A conflict can result from a merge operation. If that
|
||
happens, you should resolve it before committing the
|
||
new revision. @xref{Conflicts example}.
|
||
|
||
The @code{checkout} command also supports the @samp{-j @var{branch}} flag. The
|
||
same effect as above could be achieved with this:
|
||
|
||
@example
|
||
$ cvs checkout -j R1fix mod
|
||
$ cvs commit -m "Included R1fix"
|
||
@end example
|
||
|
||
@node Merging more than once
|
||
@section Merging from a branch several times
|
||
|
||
Continuing our example, the revision tree now looks
|
||
like this:
|
||
|
||
@example
|
||
+-----+ +-----+ +-----+ +-----+ +-----+
|
||
! 1.1 !----! 1.2 !----! 1.3 !----! 1.4 !----! 1.5 ! <- The main trunk
|
||
+-----+ +-----+ +-----+ +-----+ +-----+
|
||
! *
|
||
! *
|
||
! +---------+ +---------+
|
||
Branch R1fix -> +---! 1.2.2.1 !----! 1.2.2.2 !
|
||
+---------+ +---------+
|
||
@end example
|
||
|
||
where the starred line represents the merge from the
|
||
@samp{R1fix} branch to the main trunk, as just
|
||
discussed.
|
||
|
||
Now suppose that development continues on the
|
||
@samp{R1fix} branch:
|
||
|
||
@example
|
||
+-----+ +-----+ +-----+ +-----+ +-----+
|
||
! 1.1 !----! 1.2 !----! 1.3 !----! 1.4 !----! 1.5 ! <- The main trunk
|
||
+-----+ +-----+ +-----+ +-----+ +-----+
|
||
! *
|
||
! *
|
||
! +---------+ +---------+ +---------+
|
||
Branch R1fix -> +---! 1.2.2.1 !----! 1.2.2.2 !----! 1.2.2.3 !
|
||
+---------+ +---------+ +---------+
|
||
@end example
|
||
|
||
and then you want to merge those new changes onto the
|
||
main trunk. If you just use the @code{cvs update -j
|
||
R1fix m.c} command again, @sc{cvs} will attempt to
|
||
merge again the changes which you have already merged,
|
||
which can have undesirable side effects.
|
||
|
||
So instead you need to specify that you only want to
|
||
merge the changes on the branch which have not yet been
|
||
merged into the trunk. To do that you specify two
|
||
@samp{-j} options, and @sc{cvs} merges the changes from
|
||
the first revision to the second revision. For
|
||
example, in this case the simplest way would be
|
||
|
||
@example
|
||
cvs update -j 1.2.2.2 -j R1fix m.c # @r{Merge changes from 1.2.2.2 to the}
|
||
# @r{head of the R1fix branch}
|
||
@end example
|
||
|
||
The problem with this is that you need to specify the
|
||
1.2.2.2 revision manually. A slightly better approach
|
||
might be to use the date the last merge was done:
|
||
|
||
@example
|
||
cvs update -j R1fix:yesterday -j R1fix m.c
|
||
@end example
|
||
|
||
Better yet, tag the R1fix branch after every merge into
|
||
the trunk, and then use that tag for subsequent merges:
|
||
|
||
@example
|
||
cvs update -j merged_from_R1fix_to_trunk -j R1fix m.c
|
||
@end example
|
||
|
||
@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
|
||
@node Merging two revisions
|
||
@section Merging differences between any two revisions
|
||
@cindex Merging two revisions
|
||
@cindex Revisions, merging differences between
|
||
@cindex Differences, merging
|
||
|
||
With two @samp{-j @var{revision}} flags, the @code{update}
|
||
(and @code{checkout}) command can merge the differences
|
||
between any two revisions into your working file.
|
||
|
||
@cindex Undoing a change
|
||
@cindex Removing a change
|
||
@example
|
||
$ cvs update -j 1.5 -j 1.3 backend.c
|
||
@end example
|
||
|
||
@noindent
|
||
will @emph{remove} all changes made between revision
|
||
1.3 and 1.5. Note the order of the revisions!
|
||
|
||
If you try to use this option when operating on
|
||
multiple files, remember that the numeric revisions will
|
||
probably be very different between the various files
|
||
that make up a module. You almost always use symbolic
|
||
tags rather than revision numbers when operating on
|
||
multiple files.
|
||
|
||
@node Merging adds and removals
|
||
@section Merging can add or remove files
|
||
|
||
If the changes which you are merging involve removing
|
||
or adding some files, @code{update -j} will reflect
|
||
such additions or removals.
|
||
|
||
@c FIXME: This example needs a lot more explanation.
|
||
@c We also need other examples for some of the other
|
||
@c cases (not all--there are too many--as long as we present a
|
||
@c coherent general principle).
|
||
For example:
|
||
@example
|
||
cvs update -A
|
||
touch a b c
|
||
cvs add a b c ; cvs ci -m "added" a b c
|
||
cvs tag -b branchtag
|
||
cvs update -r branchtag
|
||
touch d ; cvs add d
|
||
rm a ; cvs rm a
|
||
cvs ci -m "added d, removed a"
|
||
cvs update -A
|
||
cvs update -jbranchtag
|
||
@end example
|
||
|
||
@c ---------------------------------------------------------------------
|
||
@node Recursive behavior
|
||
@chapter Recursive behavior
|
||
@cindex Recursive (directory descending)
|
||
@cindex Directory, descending
|
||
@cindex Descending directories
|
||
@cindex Subdirectories
|
||
|
||
Almost all of the subcommands of @sc{cvs} work
|
||
recursively when you specify a directory as an
|
||
argument. For instance, consider this directory
|
||
structure:
|
||
|
||
@example
|
||
@code{$HOME}
|
||
|
|
||
+--@t{tc}
|
||
| |
|
||
+--@t{CVS}
|
||
| (internal @sc{cvs} files)
|
||
+--@t{Makefile}
|
||
+--@t{backend.c}
|
||
+--@t{driver.c}
|
||
+--@t{frontend.c}
|
||
+--@t{parser.c}
|
||
+--@t{man}
|
||
| |
|
||
| +--@t{CVS}
|
||
| | (internal @sc{cvs} files)
|
||
| +--@t{tc.1}
|
||
|
|
||
+--@t{testing}
|
||
|
|
||
+--@t{CVS}
|
||
| (internal @sc{cvs} files)
|
||
+--@t{testpgm.t}
|
||
+--@t{test2.t}
|
||
@end example
|
||
|
||
@noindent
|
||
If @file{tc} is the current working directory, the
|
||
following is true:
|
||
|
||
@itemize @bullet
|
||
@item
|
||
@samp{cvs update testing} is equivalent to
|
||
|
||
@example
|
||
cvs update testing/testpgm.t testing/test2.t
|
||
@end example
|
||
|
||
@item
|
||
@samp{cvs update testing man} updates all files in the
|
||
subdirectories
|
||
|
||
@item
|
||
@samp{cvs update .} or just @samp{cvs update} updates
|
||
all files in the @code{tc} module
|
||
@end itemize
|
||
|
||
If no arguments are given to @code{update} it will
|
||
update all files in the current working directory and
|
||
all its subdirectories. In other words, @file{.} is a
|
||
default argument to @code{update}. This is also true
|
||
for most of the @sc{cvs} subcommands, not only the
|
||
@code{update} command.
|
||
|
||
The recursive behavior of the @sc{cvs} subcommands can be
|
||
turned off with the @samp{-l} option.
|
||
Conversely, the @samp{-R} option can be used to force recursion if
|
||
@samp{-l} is specified in @file{~/.cvsrc} (@pxref{~/.cvsrc}).
|
||
|
||
@example
|
||
$ cvs update -l # @r{Don't update files in subdirectories}
|
||
@end example
|
||
|
||
@c ---------------------------------------------------------------------
|
||
@node Adding files
|
||
@chapter Adding files to a directory
|
||
@cindex Adding files
|
||
|
||
To add a new file to a directory, follow these steps.
|
||
|
||
@itemize @bullet
|
||
@item
|
||
You must have a working copy of the directory.
|
||
@xref{Getting the source}.
|
||
|
||
@item
|
||
Create the new file inside your working copy of the directory.
|
||
|
||
@item
|
||
Use @samp{cvs add @var{filename}} to tell @sc{cvs} that you
|
||
want to version control the file. If the file contains
|
||
binary data, specify @samp{-kb} (@pxref{Binary files}).
|
||
|
||
@item
|
||
Use @samp{cvs commit @var{filename}} to actually check
|
||
in the file into the repository. Other developers
|
||
cannot see the file until you perform this step.
|
||
@end itemize
|
||
|
||
You can also use the @code{add} command to add a new
|
||
directory.
|
||
@c FIXCVS and/or FIXME: Adding a directory doesn't
|
||
@c require the commit step. This probably can be
|
||
@c considered a CVS bug, but it is possible we should
|
||
@c warn people since this behavior probably won't be
|
||
@c changing right away.
|
||
|
||
Unlike most other commands, the @code{add} command is
|
||
not recursive. You cannot even type @samp{cvs add
|
||
foo/bar}! Instead, you have to
|
||
@c FIXCVS: This is, of course, not a feature. It is
|
||
@c just that noone has gotten around to fixing "cvs add
|
||
@c foo/bar".
|
||
|
||
@example
|
||
$ cd foo
|
||
$ cvs add bar
|
||
@end example
|
||
|
||
@cindex add (subcommand)
|
||
@deffn Command {cvs add} [@code{-k} kflag] [@code{-m} message] files @dots{}
|
||
|
||
Schedule @var{files} to be added to the repository.
|
||
The files or directories specified with @code{add} must
|
||
already exist in the current directory. To add a whole
|
||
new directory hierarchy to the source repository (for
|
||
example, files received from a third-party vendor), use
|
||
the @code{import} command instead. @xref{import}.
|
||
|
||
The added files are not placed in the source repository
|
||
until you use @code{commit} to make the change
|
||
permanent. Doing an @code{add} on a file that was
|
||
removed with the @code{remove} command will undo the
|
||
effect of the @code{remove}, unless a @code{commit}
|
||
command intervened. @xref{Removing files}, for an
|
||
example.
|
||
|
||
The @samp{-k} option specifies the default way that
|
||
this file will be checked out; for more information see
|
||
@ref{Substitution modes}.
|
||
|
||
@c As noted in BUGS, -m is broken client/server (Nov
|
||
@c 96). Also see testsuite log2-* tests.
|
||
The @samp{-m} option specifies a description for the
|
||
file. This description appears in the history log (if
|
||
it is enabled, @pxref{history file}). It will also be
|
||
saved in the version history inside the repository when
|
||
the file is committed. The @code{log} command displays
|
||
this description. The description can be changed using
|
||
@samp{admin -t}. @xref{admin}. If you omit the
|
||
@samp{-m @var{description}} flag, an empty string will
|
||
be used. You will not be prompted for a description.
|
||
@end deffn
|
||
|
||
For example, the following commands add the file
|
||
@file{backend.c} to the repository:
|
||
|
||
@c This example used to specify
|
||
@c -m "Optimizer and code generation passes."
|
||
@c to the cvs add command, but that doesn't work
|
||
@c client/server (see log2 in sanity.sh). Should fix CVS,
|
||
@c but also seems strange to document things which
|
||
@c don't work...
|
||
@example
|
||
$ cvs add backend.c
|
||
$ cvs commit -m "Early version. Not yet compilable." backend.c
|
||
@end example
|
||
|
||
When you add a file it is added only on the branch
|
||
which you are working on (@pxref{Revisions and branches}). You can
|
||
later merge the additions to another branch if you want
|
||
(@pxref{Merging adds and removals}).
|
||
@c Should we mention that earlier versions of CVS
|
||
@c lacked this feature (1.3) or implemented it in a buggy
|
||
@c way (well, 1.8 had many bugs in cvs update -j)?
|
||
@c Should we mention the bug/limitation regarding a
|
||
@c file being a regular file on one branch and a directory
|
||
@c on another?
|
||
@c FIXME: This needs an example, or several, here or
|
||
@c elsewhere, for it to make much sense.
|
||
@c Somewhere we need to discuss the aspects of death
|
||
@c support which don't involve branching, I guess.
|
||
@c Like the ability to re-create a release from a tag.
|
||
|
||
@c ---------------------------------------------------------------------
|
||
@node Removing files
|
||
@chapter Removing files
|
||
@cindex Removing files
|
||
@cindex Deleting files
|
||
|
||
@c FIXME: this node wants to be split into several
|
||
@c smaller nodes. Probably would fit well with merging
|
||
@c this chapter with "adding files" and the others, as
|
||
@c suggested at the top-level menu (death support could
|
||
@c be its own section, for example, as could the
|
||
@c various bits about undoing mistakes in adding and
|
||
@c removing).
|
||
Modules change. New files are added, and old files
|
||
disappear. Still, you want to be able to retrieve an
|
||
exact copy of old releases.
|
||
|
||
Here is what you can do to remove a file,
|
||
but remain able to retrieve old revisions:
|
||
|
||
@itemize @bullet
|
||
@c FIXME: should probably be saying something about
|
||
@c having a working directory in the first place.
|
||
@item
|
||
Make sure that you have not made any uncommitted
|
||
modifications to the file. @xref{Viewing differences},
|
||
for one way to do that. You can also use the
|
||
@code{status} or @code{update} command. If you remove
|
||
the file without committing your changes, you will of
|
||
course not be able to retrieve the file as it was
|
||
immediately before you deleted it.
|
||
|
||
@item
|
||
Remove the file from your working copy of the directory.
|
||
You can for instance use @code{rm}.
|
||
|
||
@item
|
||
Use @samp{cvs remove @var{filename}} to tell @sc{cvs} that
|
||
you really want to delete the file.
|
||
|
||
@item
|
||
Use @samp{cvs commit @var{filename}} to actually
|
||
perform the removal of the file from the repository.
|
||
@end itemize
|
||
|
||
@c FIXME: Somehow this should be linked in with a more
|
||
@c general discussion of death support. I don't know
|
||
@c whether we want to use the term "death support" or
|
||
@c not (we can perhaps get by without it), but we do
|
||
@c need to discuss the "dead" state in "cvs log" and
|
||
@c related subjects. The current discussion is
|
||
@c scattered around, and not xref'd to each other.
|
||
@c FIXME: I think this paragraph wants to be moved
|
||
@c later down, at least after the first example.
|
||
When you commit the removal of the file, @sc{cvs}
|
||
records the fact that the file no longer exists. It is
|
||
possible for a file to exist on only some branches and
|
||
not on others, or to re-add another file with the same
|
||
name later. CVS will correctly create or not create
|
||
the file, based on the @samp{-r} and @samp{-D} options
|
||
specified to @code{checkout} or @code{update}.
|
||
|
||
@c FIXME: This style seems to clash with how we
|
||
@c document things in general.
|
||
@cindex Remove (subcommand)
|
||
@deffn Command {cvs remove} [options] files @dots{}
|
||
|
||
Schedule file(s) to be removed from the repository
|
||
(files which have not already been removed from the
|
||
working directory are not processed). This command
|
||
does not actually remove the file from the repository
|
||
until you commit the removal. For a full list of
|
||
options, see @ref{Invoking CVS}.
|
||
@end deffn
|
||
|
||
Here is an example of removing several files:
|
||
|
||
@example
|
||
$ cd test
|
||
$ rm *.c
|
||
$ cvs remove
|
||
cvs remove: Removing .
|
||
cvs remove: scheduling a.c for removal
|
||
cvs remove: scheduling b.c for removal
|
||
cvs remove: use 'cvs commit' to remove these files permanently
|
||
$ cvs ci -m "Removed unneeded files"
|
||
cvs commit: Examining .
|
||
cvs commit: Committing .
|
||
@end example
|
||
|
||
As a convenience you can remove the file and @code{cvs
|
||
remove} it in one step, by specifying the @samp{-f}
|
||
option. For example, the above example could also be
|
||
done like this:
|
||
|
||
@example
|
||
$ cd test
|
||
$ cvs remove -f *.c
|
||
cvs remove: scheduling a.c for removal
|
||
cvs remove: scheduling b.c for removal
|
||
cvs remove: use 'cvs commit' to remove these files permanently
|
||
$ cvs ci -m "Removed unneeded files"
|
||
cvs commit: Examining .
|
||
cvs commit: Committing .
|
||
@end example
|
||
|
||
If you execute @code{remove} for a file, and then
|
||
change your mind before you commit, you can undo the
|
||
@code{remove} with an @code{add} command.
|
||
@ignore
|
||
@c is this worth saying or not? Somehow it seems
|
||
@c confusing to me.
|
||
Of course,
|
||
since you have removed your copy of file in the working
|
||
directory, @sc{cvs} does not necessarily bring back the
|
||
contents of the file from right before you executed
|
||
@code{remove}; instead it gets the file from the
|
||
repository again.
|
||
@end ignore
|
||
|
||
@c FIXME: what if you change your mind after you commit
|
||
@c it? (answer is also "cvs add" but we don't say that...).
|
||
@c We need some index entries for thinks like "undoing
|
||
@c removal" too.
|
||
|
||
@example
|
||
$ ls
|
||
CVS ja.h oj.c
|
||
$ rm oj.c
|
||
$ cvs remove oj.c
|
||
cvs remove: scheduling oj.c for removal
|
||
cvs remove: use 'cvs commit' to remove this file permanently
|
||
$ cvs add oj.c
|
||
U oj.c
|
||
cvs add: oj.c, version 1.1.1.1, resurrected
|
||
@end example
|
||
|
||
If you realize your mistake before you run the
|
||
@code{remove} command you can use @code{update} to
|
||
resurrect the file:
|
||
|
||
@example
|
||
$ rm oj.c
|
||
$ cvs update oj.c
|
||
cvs update: warning: oj.c was lost
|
||
U oj.c
|
||
@end example
|
||
|
||
When you remove a file it is removed only on the branch
|
||
which you are working on (@pxref{Revisions and branches}). You can
|
||
later merge the removals to another branch if you want
|
||
(@pxref{Merging adds and removals}).
|
||
|
||
@node Removing directories
|
||
@chapter Removing directories
|
||
@cindex removing directories
|
||
@cindex directories, removing
|
||
|
||
In concept removing directories is somewhat similar to
|
||
removing files---you want the directory to not exist in
|
||
your current working directories, but you also want to
|
||
be able to retrieve old releases in which the directory
|
||
existed.
|
||
|
||
The way that you remove a directory is to remove all
|
||
the files in it. Then specify the @samp{-P} option to
|
||
@code{cvs update}, @code{cvs checkout}, or @code{cvs
|
||
export}, which will cause @sc{cvs} to remove empty
|
||
directories from working directories. Probably the
|
||
best way to do this is to always specify @samp{-P}; if
|
||
you want an empty directory then put a dummy file (for
|
||
example @file{.keepme}) in it to prevent @samp{-P} from
|
||
removing it.
|
||
|
||
@c I'd try to give a rationale for this, but I'm not
|
||
@c sure there is a particularly convincing one. What
|
||
@c we would _like_ is for CVS to do a better job of version
|
||
@c controlling whether directories exist, to eliminate the
|
||
@c need for -P and so that a file can be a directory in
|
||
@c one revision and a regular file in another.
|
||
Note that @samp{-P} is implied by the @samp{-r} or @samp{-D}
|
||
options of @code{checkout} and @code{export}. This way
|
||
@sc{cvs} will be able to correctly create the directory
|
||
or not depending on whether the particular version you
|
||
are checking out contains any files in that directory.
|
||
|
||
@c ---------------------------------------------------------------------
|
||
@node Tracking sources
|
||
@chapter Tracking third-party sources
|
||
@cindex Third-party sources
|
||
@cindex Tracking sources
|
||
|
||
@c FIXME: Need discussion of added and removed files.
|
||
@c FIXME: This doesn't really adequately introduce the
|
||
@c concepts of "vendor" and "you". They don't *have*
|
||
@c to be separate organizations or separate people.
|
||
@c We want a description which is somewhat more based on
|
||
@c the technical issues of which sources go where, but
|
||
@c also with enough examples of how this relates to
|
||
@c relationships like customer-supplier, developer-QA,
|
||
@c maintainer-contributor, or whatever, to make it
|
||
@c seem concrete.
|
||
If you modify a program to better fit your site, you
|
||
probably want to include your modifications when the next
|
||
release of the program arrives. @sc{cvs} can help you with
|
||
this task.
|
||
|
||
@cindex Vendor
|
||
@cindex Vendor branch
|
||
@cindex Branch, vendor-
|
||
In the terminology used in @sc{cvs}, the supplier of the
|
||
program is called a @dfn{vendor}. The unmodified
|
||
distribution from the vendor is checked in on its own
|
||
branch, the @dfn{vendor branch}. @sc{cvs} reserves branch
|
||
1.1.1 for this use.
|
||
|
||
When you modify the source and commit it, your revision
|
||
will end up on the main trunk. When a new release is
|
||
made by the vendor, you commit it on the vendor branch
|
||
and copy the modifications onto the main trunk.
|
||
|
||
Use the @code{import} command to create and update
|
||
the vendor branch. After a successful @code{import}
|
||
the vendor branch is made the `head' revision, so
|
||
anyone that checks out a copy of the file gets that
|
||
revision. When a local modification is committed it is
|
||
placed on the main trunk, and made the `head'
|
||
revision.
|
||
|
||
@menu
|
||
* First import:: Importing a module for the first time
|
||
* Update imports:: Updating a module with the import command
|
||
* Reverting local changes:: Reverting a module to the latest vendor release
|
||
* Binary files in imports:: Binary files require special handling
|
||
* Keywords in imports:: Keyword substitution might be undesirable
|
||
@end menu
|
||
|
||
@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
|
||
@node First import
|
||
@section Importing a module for the first time
|
||
@cindex Importing modules
|
||
|
||
@c Should mention naming conventions for vendor tags,
|
||
@c release tags, and perhaps directory names.
|
||
Use the @code{import} command to check in the sources
|
||
for the first time. When you use the @code{import}
|
||
command to track third-party sources, the @dfn{vendor
|
||
tag} and @dfn{release tags} are useful. The
|
||
@dfn{vendor tag} is a symbolic name for the branch
|
||
(which is always 1.1.1, unless you use the @samp{-b
|
||
@var{branch}} flag---@xref{import options}.). The
|
||
@dfn{release tags} are symbolic names for a particular
|
||
release, such as @samp{FSF_0_04}.
|
||
|
||
@c I'm not completely sure this belongs here. But
|
||
@c we need to say it _somewhere_ reasonably obvious; it
|
||
@c is a common misconception among people first learning CVS
|
||
Note that @code{import} does @emph{not} change the
|
||
directory in which you invoke it. In particular, it
|
||
does not set up that directory as a @sc{cvs} working
|
||
directory; if you want to work with the sources import
|
||
them first and then check them out into a different
|
||
directory (@pxref{Getting the source}).
|
||
|
||
@cindex Wdiff (import example)
|
||
Suppose you have the sources to a program called
|
||
@code{wdiff} in a directory @file{wdiff-0.04},
|
||
and are going to make private modifications that you
|
||
want to be able to use even when new releases are made
|
||
in the future. You start by importing the source to
|
||
your repository:
|
||
|
||
@example
|
||
$ cd wdiff-0.04
|
||
$ cvs import -m "Import of FSF v. 0.04" fsf/wdiff FSF_DIST WDIFF_0_04
|
||
@end example
|
||
|
||
The vendor tag is named @samp{FSF_DIST} in the above
|
||
example, and the only release tag assigned is
|
||
@samp{WDIFF_0_04}.
|
||
@c FIXME: Need to say where fsf/wdiff comes from.
|
||
|
||
@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
|
||
@node Update imports
|
||
@section Updating a module with the import command
|
||
|
||
When a new release of the source arrives, you import it into the
|
||
repository with the same @code{import} command that you used to set up
|
||
the repository in the first place. The only difference is that you
|
||
specify a different release tag this time.
|
||
|
||
@example
|
||
$ tar xfz wdiff-0.05.tar.gz
|
||
$ cd wdiff-0.05
|
||
$ cvs import -m "Import of FSF v. 0.05" fsf/wdiff FSF_DIST WDIFF_0_05
|
||
@end example
|
||
|
||
For files that have not been modified locally, the newly created
|
||
revision becomes the head revision. If you have made local
|
||
changes, @code{import} will warn you that you must merge the changes
|
||
into the main trunk, and tell you to use @samp{checkout -j} to do so.
|
||
|
||
@c FIXME: why "wdiff" here and "fsf/wdiff" in the
|
||
@c "import"? I think the assumption is that one has
|
||
@c "wdiff fsf/wdiff" or some such in modules, but it
|
||
@c would be better to not use modules in this example.
|
||
@example
|
||
$ cvs checkout -jFSF_DIST:yesterday -jFSF_DIST wdiff
|
||
@end example
|
||
|
||
@noindent
|
||
The above command will check out the latest revision of
|
||
@samp{wdiff}, merging the changes made on the vendor branch @samp{FSF_DIST}
|
||
since yesterday into the working copy. If any conflicts arise during
|
||
the merge they should be resolved in the normal way (@pxref{Conflicts
|
||
example}). Then, the modified files may be committed.
|
||
|
||
Using a date, as suggested above, assumes that you do
|
||
not import more than one release of a product per
|
||
day. If you do, you can always use something like this
|
||
instead:
|
||
|
||
@example
|
||
$ cvs checkout -jWDIFF_0_04 -jWDIFF_0_05 wdiff
|
||
@end example
|
||
|
||
@noindent
|
||
In this case, the two above commands are equivalent.
|
||
|
||
@node Reverting local changes
|
||
@section Reverting to the latest vendor release
|
||
|
||
You can also revert local changes completely and return
|
||
to the latest vendor release by changing the `head'
|
||
revision back to the vendor branch on all files. For
|
||
example, if you have a checked-out copy of the sources
|
||
in @file{~/work.d/wdiff}, and you want to revert to the
|
||
vendor's version for all the files in that directory,
|
||
you would type:
|
||
|
||
@example
|
||
$ cd ~/work.d/wdiff
|
||
$ cvs admin -bWDIFF .
|
||
@end example
|
||
|
||
@noindent
|
||
You must specify the @samp{-bWDIFF} without any space
|
||
after the @samp{-b}. @xref{admin options}.
|
||
|
||
@node Binary files in imports
|
||
@section How to handle binary files with cvs import
|
||
|
||
Use the @samp{-k} wrapper option to tell import which
|
||
files are binary. @xref{Wrappers}.
|
||
|
||
@node Keywords in imports
|
||
@section How to handle keyword substitution with cvs import
|
||
|
||
The sources which you are importing may contain
|
||
keywords (@pxref{Keyword substitution}). For example,
|
||
the vendor may use @sc{cvs} or some other system
|
||
which uses similar keyword expansion syntax. If you
|
||
just import the files in the default fashion, then
|
||
the keyword expansions supplied by the vendor will
|
||
be replaced by keyword expansions supplied by your
|
||
own copy of @sc{cvs}. It may be more convenient to
|
||
maintain the expansions supplied by the vendor, so
|
||
that this information can supply information about
|
||
the sources that you imported from the vendor.
|
||
|
||
To maintain the keyword expansions supplied by the
|
||
vendor, supply the @samp{-ko} option to @code{cvs
|
||
import} the first time you import the file.
|
||
This will turn off keyword expansion
|
||
for that file entirely, so if you want to be more
|
||
selective you'll have to think about what you want
|
||
and use the @samp{-k} option to @code{cvs update} or
|
||
@code{cvs admin} as appropriate.
|
||
@c Supplying -ko to import if the file already existed
|
||
@c has no effect. Not clear to me whether it should
|
||
@c or not.
|
||
|
||
@c ---------------------------------------------------------------------
|
||
@node Moving files
|
||
@chapter Moving and renaming files
|
||
@cindex Moving files
|
||
@cindex Renaming files
|
||
@cindex Files, moving
|
||
|
||
Moving files to a different directory or renaming them
|
||
is not difficult, but some of the ways in which this
|
||
works may be non-obvious. (Moving or renaming a
|
||
directory is even harder. @xref{Moving directories}.).
|
||
|
||
The examples below assume that the file @var{old} is renamed to
|
||
@var{new}.
|
||
|
||
@menu
|
||
* Outside:: The normal way to Rename
|
||
* Inside:: A tricky, alternative way
|
||
* Rename by copying:: Another tricky, alternative way
|
||
@end menu
|
||
|
||
@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
|
||
@node Outside
|
||
@section The Normal way to Rename
|
||
|
||
@c More rename issues. Not sure whether these are
|
||
@c worth documenting; I'm putting them here because
|
||
@c it seems to be as good a place as any to try to
|
||
@c set down the issues.
|
||
@c * "cvs annotate" will annotate either the new
|
||
@c file or the old file; it cannot annotate _each
|
||
@c line_ based on whether it was last changed in the
|
||
@c new or old file. Unlike "cvs log", where the
|
||
@c consequences of having to select either the new
|
||
@c or old name seem fairly benign, this may be a
|
||
@c real advantage to having CVS know about renames
|
||
@c other than as a deletion and an addition.
|
||
|
||
The normal way to move a file is to copy @var{old} to
|
||
@var{new}, and then issue the normal @sc{cvs} commands
|
||
to remove @var{old} from the repository, and add
|
||
@var{new} to it.
|
||
@c The following sentence is not true: one must cd into
|
||
@c the directory to run "cvs add".
|
||
@c (Both @var{old} and @var{new} could
|
||
@c contain relative paths, for example @file{foo/bar.c}).
|
||
|
||
@example
|
||
$ mv @var{old} @var{new}
|
||
$ cvs remove @var{old}
|
||
$ cvs add @var{new}
|
||
$ cvs commit -m "Renamed @var{old} to @var{new}" @var{old} @var{new}
|
||
@end example
|
||
|
||
This is the simplest way to move a file, it is not
|
||
error-prone, and it preserves the history of what was
|
||
done. Note that to access the history of the file you
|
||
must specify the old or the new name, depending on what
|
||
portion of the history you are accessing. For example,
|
||
@code{cvs log @var{old}} will give the log up until the
|
||
time of the rename.
|
||
|
||
When @var{new} is committed its revision numbers will
|
||
start again, usually at 1.1, so if that bothers you,
|
||
use the @samp{-r rev} option to commit. For more
|
||
information see @ref{Assigning revisions}.
|
||
|
||
@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
|
||
@node Inside
|
||
@section Moving the history file
|
||
|
||
This method is more dangerous, since it involves moving
|
||
files inside the repository. Read this entire section
|
||
before trying it out!
|
||
|
||
@example
|
||
$ cd $CVSROOT/@var{module}
|
||
$ mv @var{old},v @var{new},v
|
||
@end example
|
||
|
||
@noindent
|
||
Advantages:
|
||
|
||
@itemize @bullet
|
||
@item
|
||
The log of changes is maintained intact.
|
||
|
||
@item
|
||
The revision numbers are not affected.
|
||
@end itemize
|
||
|
||
@noindent
|
||
Disadvantages:
|
||
|
||
@itemize @bullet
|
||
@item
|
||
Old releases of the module cannot easily be fetched from the
|
||
repository. (The file will show up as @var{new} even
|
||
in revisions from the time before it was renamed).
|
||
|
||
@item
|
||
There is no log information of when the file was renamed.
|
||
|
||
@item
|
||
Nasty things might happen if someone accesses the history file
|
||
while you are moving it. Make sure no one else runs any of the @sc{cvs}
|
||
commands while you move it.
|
||
@end itemize
|
||
|
||
@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
|
||
@node Rename by copying
|
||
@section Copying the history file
|
||
|
||
This way also involves direct modifications to the
|
||
repository. It is safe, but not without drawbacks.
|
||
|
||
@example
|
||
# @r{Copy the @sc{rcs} file inside the repository}
|
||
$ cd $CVSROOT/@var{module}
|
||
$ cp @var{old},v @var{new},v
|
||
# @r{Remove the old file}
|
||
$ cd ~/@var{module}
|
||
$ rm @var{old}
|
||
$ cvs remove @var{old}
|
||
$ cvs commit @var{old}
|
||
# @r{Remove all tags from @var{new}}
|
||
$ cvs update @var{new}
|
||
$ cvs log @var{new} # @r{Remember the non-branch tag names}
|
||
$ cvs tag -d @var{tag1} @var{new}
|
||
$ cvs tag -d @var{tag2} @var{new}
|
||
@dots{}
|
||
@end example
|
||
|
||
By removing the tags you will be able to check out old
|
||
revisions of the module.
|
||
|
||
@noindent
|
||
Advantages:
|
||
|
||
@itemize @bullet
|
||
@item
|
||
@c FIXME: Is this true about -D now that we have death
|
||
@c support? See 5B.3 in the FAQ.
|
||
Checking out old revisions works correctly, as long as
|
||
you use @samp{-r@var{tag}} and not @samp{-D@var{date}}
|
||
to retrieve the revisions.
|
||
|
||
@item
|
||
The log of changes is maintained intact.
|
||
|
||
@item
|
||
The revision numbers are not affected.
|
||
@end itemize
|
||
|
||
@noindent
|
||
Disadvantages:
|
||
|
||
@itemize @bullet
|
||
@item
|
||
You cannot easily see the history of the file across the rename.
|
||
|
||
@ignore
|
||
@c Is this true? I don't see how the revision numbers
|
||
@c _could_ start over, when new,v is just old,v with
|
||
@c the tags deleted.
|
||
@c If there is some need to reinstate this text,
|
||
@c it is "usually 1.1", not "1.0" and it needs an
|
||
@c xref to Assigning revisions
|
||
@item
|
||
Unless you use the @samp{-r rev} (@pxref{commit
|
||
options}) flag when @var{new} is committed its revision
|
||
numbers will start at 1.0 again.
|
||
@end ignore
|
||
@end itemize
|
||
|
||
@c ---------------------------------------------------------------------
|
||
@node Moving directories
|
||
@chapter Moving and renaming directories
|
||
@cindex Moving directories
|
||
@cindex Renaming directories
|
||
@cindex Directories, moving
|
||
|
||
The normal way to rename or move a directory is to
|
||
rename or move each file within it as described in
|
||
@ref{Outside}. Then check out with the @samp{-P}
|
||
option, as described in @ref{Removing directories}.
|
||
|
||
If you really want to hack the repository to rename or
|
||
delete a directory in the repository, you can do it
|
||
like this:
|
||
|
||
@enumerate
|
||
@item
|
||
Inform everyone who has a copy of the module that the
|
||
directory will be renamed. They should commit all
|
||
their changes, and remove their working copies of the
|
||
module, before you take the steps below.
|
||
|
||
@item
|
||
Rename the directory inside the repository.
|
||
|
||
@example
|
||
$ cd $CVSROOT/@var{module}
|
||
$ mv @var{old-dir} @var{new-dir}
|
||
@end example
|
||
|
||
@item
|
||
Fix the @sc{cvs} administrative files, if necessary (for
|
||
instance if you renamed an entire module).
|
||
|
||
@item
|
||
Tell everyone that they can check out the module and continue
|
||
working.
|
||
|
||
@end enumerate
|
||
|
||
If someone had a working copy of the module the @sc{cvs} commands will
|
||
cease to work for him, until he removes the directory
|
||
that disappeared inside the repository.
|
||
|
||
It is almost always better to move the files in the
|
||
directory instead of moving the directory. If you move the
|
||
directory you are unlikely to be able to retrieve old
|
||
releases correctly, since they probably depend on the
|
||
name of the directories.
|
||
|
||
@c ---------------------------------------------------------------------
|
||
@node History browsing
|
||
@chapter History browsing
|
||
@cindex History browsing
|
||
@cindex Traceability
|
||
@cindex Isolation
|
||
|
||
@ignore
|
||
@c This is too long for an introduction (goal is
|
||
@c one 20x80 character screen), and also mixes up a
|
||
@c variety of issues (parallel development, history,
|
||
@c maybe even touches on process control).
|
||
|
||
@c -- @quote{To lose ones history is to lose ones soul.}
|
||
@c -- ///
|
||
@c -- ///Those who cannot remember the past are condemned to repeat it.
|
||
@c -- /// -- George Santayana
|
||
@c -- ///
|
||
|
||
@sc{cvs} tries to make it easy for a group of people to work
|
||
together. This is done in two ways:
|
||
|
||
@itemize @bullet
|
||
@item
|
||
Isolation---You have your own working copy of the
|
||
source. You are not affected by modifications made by
|
||
others until you decide to incorporate those changes
|
||
(via the @code{update} command---@pxref{update}).
|
||
|
||
@item
|
||
Traceability---When something has changed, you can
|
||
always see @emph{exactly} what changed.
|
||
@end itemize
|
||
|
||
There are several features of @sc{cvs} that together lead
|
||
to traceability:
|
||
|
||
@itemize @bullet
|
||
@item
|
||
Each revision of a file has an accompanying log
|
||
message.
|
||
|
||
@item
|
||
All commits are optionally logged to a central history
|
||
database.
|
||
|
||
@item
|
||
Logging information can be sent to a user-defined
|
||
program (@pxref{loginfo}).
|
||
@end itemize
|
||
|
||
@c -- More text here.
|
||
|
||
This chapter should talk about the history file, the
|
||
@code{log} command, the usefulness of ChangeLogs
|
||
even when you run @sc{cvs}, and things like that.
|
||
|
||
@end ignore
|
||
|
||
@c kind of lame, in a lot of ways the above text inside
|
||
@c the @ignore motivates this chapter better
|
||
Once you have used @sc{cvs} to store a version control
|
||
history---what files have changed when, how, and by
|
||
whom, there are a variety of mechanisms for looking
|
||
through the history.
|
||
|
||
@c FIXME: should also be talking about how you look at
|
||
@c old revisions (e.g. "cvs update -p -r 1.2 foo.c").
|
||
@menu
|
||
* log messages:: Log messages
|
||
* history database:: The history database
|
||
* user-defined logging:: User-defined logging
|
||
* annotate:: What revision modified each line of a file?
|
||
@end menu
|
||
|
||
@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
|
||
@node log messages
|
||
@section Log messages
|
||
|
||
@c FIXME: @xref to place where we talk about how to
|
||
@c specify message to commit.
|
||
Whenever you commit a file you specify a log message.
|
||
|
||
@c FIXME: bring the information here, and get rid of or
|
||
@c greatly shrink the "log" node.
|
||
To look through the log messages which have been
|
||
specified for every revision which has been committed,
|
||
use the @code{cvs log} command (@pxref{log}).
|
||
|
||
@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
|
||
@node history database
|
||
@section The history database
|
||
|
||
@c FIXME: bring the information from the history file
|
||
@c and history nodes here. Rewrite it to be motivated
|
||
@c better (start out by clearly explaining what gets
|
||
@c logged in history, for example).
|
||
You can use the history file (@pxref{history file}) to
|
||
log various @sc{cvs} actions. To retrieve the
|
||
information from the history file, use the @code{cvs
|
||
history} command (@pxref{history}).
|
||
@c
|
||
@c The history database has many problems:
|
||
@c * It is very unclear what field means what. This
|
||
@c could be improved greatly by better documentation,
|
||
@c but there are still non-orthogonalities (for
|
||
@c example, tag does not record the "repository"
|
||
@c field but most records do).
|
||
@c * Confusion about files, directories, and modules.
|
||
@c Some commands record one, some record others.
|
||
@c * File removal is not logged. There is an 'R'
|
||
@c record type documented, but CVS never uses it.
|
||
@c * Tags are only logged for the "cvs rtag" command,
|
||
@c not "cvs tag". The fix for this is not completely
|
||
@c clear (see above about modules vs. files).
|
||
@c * Are there other cases of operations that are not
|
||
@c logged? One would hope for all changes to the
|
||
@c repository to be logged somehow (particularly
|
||
@c operations like tagging, "cvs admin -k", and other
|
||
@c operations which do not record a history that one
|
||
@c can get with "cvs log"). Operations on the working
|
||
@c directory, like export, get, and release, are a
|
||
@c second category also covered by the current "cvs
|
||
@c history".
|
||
@c * The history file does not record the options given
|
||
@c to a command. The most serious manifestation of
|
||
@c this is perhaps that it doesn't record whether a command
|
||
@c was recursive. It is not clear to me whether one
|
||
@c wants to log at a level very close to the command
|
||
@c line, as a sort of way of logging each command
|
||
@c (more or less), or whether one wants
|
||
@c to log more at the level of what was changed (or
|
||
@c something in between), but either way the current
|
||
@c information has pretty big gaps.
|
||
@c * Further details about a tag--like whether it is a
|
||
@c branch tag or, if a non-branch tag, which branch it
|
||
@c is on. One can find out this information about the
|
||
@c tag as it exists _now_, but if the tag has been
|
||
@c moved, one doesn't know what it was like at the time
|
||
@c the history record was written.
|
||
@c * Whether operating on a particular tag, date, or
|
||
@c options was implicit (sticky) or explicit.
|
||
@c
|
||
@c Another item, only somewhat related to the above, is a
|
||
@c way to control what is logged in the history file.
|
||
@c This is probably the only good way to handle
|
||
@c different people having different ideas about
|
||
@c information/space tradeoffs.
|
||
@c
|
||
@c It isn't really clear that it makes sense to try to
|
||
@c patch up the history file format as it exists now to
|
||
@c include all that stuff. It might be better to
|
||
@c design a whole new CVSROOT/nhistory file and "cvs
|
||
@c nhistory" command, or some such, or in some other
|
||
@c way trying to come up with a clean break from the
|
||
@c past, which can address the above concerns. Another
|
||
@c open question is how/whether this relates to
|
||
@c taginfo/loginfo/etc.
|
||
|
||
@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
|
||
@node user-defined logging
|
||
@section User-defined logging
|
||
|
||
@c FIXME: should probably also mention the fact the -l
|
||
@c global option can disable most of the mechanisms
|
||
@c discussed here (why? What is the -l global option for?).
|
||
@c
|
||
@c FIXME: probably should centralize this information
|
||
@c here, at least to some extent. Maybe by moving the
|
||
@c loginfo, etc., nodes here and replacing
|
||
@c the "user-defined logging" node with one node for
|
||
@c each method.
|
||
You can customize @sc{cvs} to log various kinds of
|
||
actions, in whatever manner you choose. These
|
||
mechanisms operate by executing a script at various
|
||
times. The script might append a message to a file
|
||
listing the information and the programmer who created
|
||
it, or send mail to a group of developers, or, perhaps,
|
||
post a message to a particular newsgroup. To log
|
||
commits, use the @file{loginfo} file (@pxref{loginfo}).
|
||
@c FIXME: What is difference between doing it in the
|
||
@c modules file and using loginfo/taginfo? Why should
|
||
@c user use one or the other?
|
||
To log commits, checkouts, exports, and tags,
|
||
respectively, you can also use the @samp{-i},
|
||
@samp{-o}, @samp{-e}, and @samp{-t} options in the
|
||
modules file. For a more flexible way of giving
|
||
notifications to various users, which requires less in
|
||
the way of keeping centralized scripts up to date, use
|
||
the @code{cvs watch add} command (@pxref{Getting
|
||
Notified}); this command is useful even if you are not
|
||
using @code{cvs watch on}.
|
||
|
||
@cindex taginfo
|
||
@cindex exit status, of taginfo
|
||
The @file{taginfo} file defines programs to execute
|
||
when someone executes a @code{tag} or @code{rtag}
|
||
command. The @file{taginfo} file has the standard form
|
||
for administrative files (@pxref{Administrative
|
||
files}), where each line is a regular expression
|
||
followed by a command to execute. The arguments passed
|
||
to the command are, in order, the @var{tagname},
|
||
@var{operation} (@code{add} for @code{tag},
|
||
@code{mov} for @code{tag -F}, and @code{del} for
|
||
@code{tag -d}), @var{repository}, and any remaining are
|
||
pairs of @var{filename} @var{revision}. A non-zero
|
||
exit of the filter program will cause the tag to be
|
||
aborted.
|
||
|
||
@node annotate
|
||
@section Annotate command
|
||
@cindex annotate (subcommand)
|
||
|
||
@deffn Command {cvs annotate} [@code{-flR}] [@code{-r rev}|@code{-D date}] files @dots{}
|
||
|
||
For each file in @var{files}, print the head revision
|
||
of the trunk, together with information on the last
|
||
modification for each line. For example:
|
||
|
||
@example
|
||
$ cvs annotate ssfile
|
||
Annotations for ssfile
|
||
***************
|
||
1.1 (mary 27-Mar-96): ssfile line 1
|
||
1.2 (joe 28-Mar-96): ssfile line 2
|
||
@end example
|
||
|
||
The file @file{ssfile} currently contains two lines.
|
||
The @code{ssfile line 1} line was checked in by
|
||
@code{mary} on March 27. Then, on March 28, @code{joe}
|
||
added a line @code{ssfile line 2}, without modifying
|
||
the @code{ssfile line 1} line. This report doesn't
|
||
tell you anything about lines which have been deleted
|
||
or replaced; you need to use @code{cvs diff} for that
|
||
(@pxref{diff}).
|
||
|
||
@end deffn
|
||
|
||
The options to @code{cvs annotate} are listed in
|
||
@ref{Invoking CVS}, and can be used to select the files
|
||
and revisions to annotate. The options are described
|
||
in more detail in @ref{Common options}.
|
||
|
||
@c FIXME: maybe an example using the options? Just
|
||
@c what it means to select a revision might be worth a
|
||
@c few words of explanation ("you want to see who
|
||
@c changed this line *before* 1.4"...).
|
||
|
||
@c ---------------------------------------------------------------------
|
||
@node Keyword substitution
|
||
@chapter Keyword substitution
|
||
@cindex Keyword substitution
|
||
@cindex Keyword expansion
|
||
@cindex Identifying files
|
||
|
||
@comment Be careful when editing this chapter.
|
||
@comment Remember that this file is kept under
|
||
@comment version control, so we must not accidentally
|
||
@comment include a valid keyword in the running text.
|
||
|
||
As long as you edit source files inside your working
|
||
copy of a module you can always find out the state of
|
||
your files via @samp{cvs status} and @samp{cvs log}.
|
||
But as soon as you export the files from your
|
||
development environment it becomes harder to identify
|
||
which revisions they are.
|
||
|
||
CVS can use a mechanism known as @dfn{keyword
|
||
substitution} (or @dfn{keyword expansion}) to help
|
||
identifying the files. Embedded strings of the form
|
||
@code{$@var{keyword}$} and
|
||
@code{$@var{keyword}:@dots{}$} in a file are replaced
|
||
with strings of the form
|
||
@code{$@var{keyword}:@var{value}$} whenever you obtain
|
||
a new revision of the file.
|
||
|
||
@menu
|
||
* Keyword list:: Keywords
|
||
* Using keywords:: Using keywords
|
||
* Avoiding substitution:: Avoiding substitution
|
||
* Substitution modes:: Substitution modes
|
||
* Log keyword:: Problems with the $@asis{}Log$ keyword.
|
||
@end menu
|
||
|
||
@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
|
||
@node Keyword list
|
||
@section RCS Keywords
|
||
@cindex RCS keywords
|
||
|
||
@c FIXME: need some kind of example here I think,
|
||
@c perhaps in a
|
||
@c "Keyword intro" node. The intro in the "Keyword
|
||
@c substitution" node itself seems OK, but to launch
|
||
@c into a list of the keywords somehow seems too abrupt.
|
||
|
||
This is a list of the keywords:
|
||
|
||
@table @code
|
||
@cindex Author keyword
|
||
@item $@asis{Author}$
|
||
The login name of the user who checked in the revision.
|
||
|
||
@cindex Date keyword
|
||
@item $@asis{Date}$
|
||
The date and time (UTC) the revision was checked in.
|
||
|
||
@cindex Header keyword
|
||
@item $@asis{Header}$
|
||
A standard header containing the full pathname of the
|
||
@sc{rcs} file, the revision number, the date (UTC), the
|
||
author, the state, and the locker (if locked). Files
|
||
will normally never be locked when you use @sc{cvs}.
|
||
|
||
@cindex Id keyword
|
||
@item $@asis{Id}$
|
||
Same as @code{$@asis{Header}$}, except that the @sc{rcs}
|
||
filename is without a path.
|
||
|
||
@cindex Name keyword
|
||
@item $@asis{Name}$
|
||
Tag name used to check out this file.
|
||
@c FIXME: should supply an example (e.g. "if you use
|
||
@c "cvs update -r foo" then Name expands to "foo"). Also
|
||
@c should add Name to testsuite (best way to ensure
|
||
@c that the example is correct!)
|
||
|
||
@cindex Locker keyword
|
||
@item $@asis{Locker}$
|
||
The login name of the user who locked the revision
|
||
(empty if not locked, and thus almost always useless
|
||
when you are using @sc{cvs}).
|
||
|
||
@cindex Log keyword
|
||
@item $@asis{Log}$
|
||
The log message supplied during commit, preceded by a
|
||
header containing the @sc{rcs} filename, the revision
|
||
number, the author, and the date (UTC). Existing log
|
||
messages are @emph{not} replaced. Instead, the new log
|
||
message is inserted after @code{$@asis{Log:@dots{}}$}.
|
||
Each new line is prefixed with a @dfn{comment leader}
|
||
which @sc{rcs} guesses from the file name extension.
|
||
It can be changed with @code{cvs admin -c}.
|
||
@xref{admin options}. This keyword is useful for
|
||
accumulating a complete change log in a source file,
|
||
but for several reasons it can be problematic.
|
||
@xref{Log keyword}.
|
||
|
||
@cindex RCSfile keyword
|
||
@item $@asis{RCSfile}$
|
||
The name of the RCS file without a path.
|
||
|
||
@cindex Revision keyword
|
||
@item $@asis{Revision}$
|
||
The revision number assigned to the revision.
|
||
|
||
@cindex Source keyword
|
||
@item $@asis{Source}$
|
||
The full pathname of the RCS file.
|
||
|
||
@cindex State keyword
|
||
@item $@asis{State}$
|
||
The state assigned to the revision. States can be
|
||
assigned with @code{cvs admin -s}---@xref{admin options}.
|
||
|
||
@end table
|
||
|
||
@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
|
||
@node Using keywords
|
||
@section Using keywords
|
||
|
||
To include a keyword string you simply include the
|
||
relevant text string, such as @code{$@asis{Id}$}, inside the
|
||
file, and commit the file. @sc{cvs} will automatically
|
||
expand the string as part of the commit operation.
|
||
|
||
@need 800
|
||
It is common to embed @code{$@asis{}Id$} string in the
|
||
C source code. This example shows the first few lines
|
||
of a typical file, after keyword substitution has been
|
||
performed:
|
||
|
||
@example
|
||
static char *rcsid="$@asis{}Id: samp.c,v 1.5 1993/10/19 14:57:32 ceder Exp $";
|
||
/* @r{The following lines will prevent @code{gcc} version 2.@var{x}}
|
||
@r{from issuing an "unused variable" warning}. */
|
||
#if __GNUC__ == 2
|
||
#define USE(var) static void * use_##var = (&use_##var, (void *) &var)
|
||
USE (rcsid);
|
||
#endif
|
||
@end example
|
||
|
||
Even though a clever optimizing compiler could remove
|
||
the unused variable @code{rcsid}, most compilers tend
|
||
to include the string in the binary. Some compilers
|
||
have a @code{#pragma} directive to include literal text
|
||
in the binary.
|
||
|
||
@cindex Ident (shell command)
|
||
The @code{ident} command (which is part of the @sc{rcs}
|
||
package) can be used to extract keywords and their
|
||
values from a file. This can be handy for text files,
|
||
but it is even more useful for extracting keywords from
|
||
binary files.
|
||
|
||
@example
|
||
$ ident samp.c
|
||
samp.c:
|
||
$@asis{}Id: samp.c,v 1.5 1993/10/19 14:57:32 ceder Exp $
|
||
$ gcc samp.c
|
||
$ ident a.out
|
||
a.out:
|
||
$@asis{}Id: samp.c,v 1.5 1993/10/19 14:57:32 ceder Exp $
|
||
@end example
|
||
|
||
@cindex What (shell command)
|
||
S@sc{ccs} is another popular revision control system.
|
||
It has a command, @code{what}, which is very similar to
|
||
@code{ident} and used for the same purpose. Many sites
|
||
without @sc{rcs} have @sc{sccs}. Since @code{what}
|
||
looks for the character sequence @code{@@(#)} it is
|
||
easy to include keywords that are detected by either
|
||
command. Simply prefix the @sc{rcs} keyword with the
|
||
magic @sc{sccs} phrase, like this:
|
||
|
||
@example
|
||
static char *id="@@(#) $@asis{}Id: ab.c,v 1.5 1993/10/19 14:57:32 ceder Exp $";
|
||
@end example
|
||
|
||
@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
|
||
@node Avoiding substitution
|
||
@section Avoiding substitution
|
||
|
||
Keyword substitution has its disadvantages. Sometimes
|
||
you might want the literal text string
|
||
@samp{$@asis{}Author$} to appear inside a file without
|
||
@sc{rcs} interpreting it as a keyword and expanding it
|
||
into something like @samp{$@asis{}Author: ceder $}.
|
||
|
||
There is unfortunately no way to selectively turn off
|
||
keyword substitution. You can use @samp{-ko}
|
||
(@pxref{Substitution modes}) to turn off keyword
|
||
substitution entirely.
|
||
|
||
In many cases you can avoid using keywords in
|
||
the source, even though they appear in the final
|
||
product. For example, the source for this manual
|
||
contains @samp{$@@asis@{@}Author$} whenever the text
|
||
@samp{$@asis{}Author$} should appear. In @code{nroff}
|
||
and @code{troff} you can embed the null-character
|
||
@code{\&} inside the keyword for a similar effect.
|
||
|
||
@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
|
||
@node Substitution modes
|
||
@section Substitution modes
|
||
@cindex -k (keyword substitution)
|
||
@cindex Kflag
|
||
|
||
@c FIXME: This could be made more coherent, by expanding it
|
||
@c with more examples or something.
|
||
Each file has a stored default substitution mode, and
|
||
each working directory copy of a file also has a
|
||
substitution mode. The former is set by the @samp{-k}
|
||
option to @code{cvs add} and @code{cvs admin}; the
|
||
latter is set by the -k or -A options to @code{cvs
|
||
checkout} or @code{cvs update}. @code{cvs diff} also
|
||
has a @samp{-k} option. For some examples,
|
||
@xref{Binary files}.
|
||
|
||
The modes available are:
|
||
|
||
@table @samp
|
||
@item -kkv
|
||
Generate keyword strings using the default form, e.g.
|
||
@code{$@asis{}Revision: 5.7 $} for the @code{Revision}
|
||
keyword.
|
||
|
||
@item -kkvl
|
||
Like @samp{-kkv}, except that a locker's name is always
|
||
inserted if the given revision is currently locked.
|
||
This option is normally not useful when @sc{cvs} is used.
|
||
|
||
@item -kk
|
||
Generate only keyword names in keyword strings; omit
|
||
their values. For example, for the @code{Revision}
|
||
keyword, generate the string @code{$@asis{}Revision$}
|
||
instead of @code{$@asis{}Revision: 5.7 $}. This option
|
||
is useful to ignore differences due to keyword
|
||
substitution when comparing different revisions of a
|
||
file.
|
||
|
||
@item -ko
|
||
Generate the old keyword string, present in the working
|
||
file just before it was checked in. For example, for
|
||
the @code{Revision} keyword, generate the string
|
||
@code{$@asis{}Revision: 1.1 $} instead of
|
||
@code{$@asis{}Revision: 5.7 $} if that is how the
|
||
string appeared when the file was checked in.
|
||
|
||
@item -kb
|
||
Like @samp{-ko}, but also inhibit conversion of line
|
||
endings between the canonical form in which they are
|
||
stored in the repository (linefeed only), and the form
|
||
appropriate to the operating system in use on the
|
||
client. For systems, like unix, which use linefeed
|
||
only to terminate lines, this is the same as
|
||
@samp{-ko}. For more information on binary files, see
|
||
@ref{Binary files}.
|
||
|
||
@item -kv
|
||
Generate only keyword values for keyword strings. For
|
||
example, for the @code{Revision} keyword, generate the string
|
||
@code{5.7} instead of @code{$@asis{}Revision: 5.7 $}.
|
||
This can help generate files in programming languages
|
||
where it is hard to strip keyword delimiters like
|
||
@code{$@asis{}Revision: $} from a string. However,
|
||
further keyword substitution cannot be performed once
|
||
the keyword names are removed, so this option should be
|
||
used with care.
|
||
|
||
One often would like to use @samp{-kv} with @code{cvs
|
||
export}---@pxref{export}. But be aware that doesn't
|
||
handle an export containing binary files correctly.
|
||
|
||
@end table
|
||
|
||
@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
|
||
@node Log keyword
|
||
@section Problems with the $@asis{}Log$ keyword.
|
||
|
||
The @code{$@asis{}Log$} keyword is somewhat
|
||
controversial. As long as you are working on your
|
||
development system the information is easily accessible
|
||
even if you do not use the @code{$@asis{}Log$}
|
||
keyword---just do a @code{cvs log}. Once you export
|
||
the file the history information might be useless
|
||
anyhow.
|
||
|
||
A more serious concern is that @sc{cvs} is not good at
|
||
handling @code{$@asis{}Log$} entries when a branch is
|
||
merged onto the main trunk. Conflicts often result
|
||
from the merging operation.
|
||
@c We say "cvs" even though it is done via rcsmerge;
|
||
@c this is an implementation detail. If the merging is
|
||
@c done in CVS instead, should check if this problem
|
||
@c still persists.
|
||
|
||
People also tend to "fix" the log entries in the file
|
||
(correcting spelling mistakes and maybe even factual
|
||
errors). If that is done the information from
|
||
@code{cvs log} will not be consistent with the
|
||
information inside the file. This may or may not be a
|
||
problem in real life.
|
||
|
||
It has been suggested that the @code{$@asis{}Log$}
|
||
keyword should be inserted @emph{last} in the file, and
|
||
not in the files header, if it is to be used at all.
|
||
That way the long list of change messages will not
|
||
interfere with everyday source file browsing.
|
||
|
||
@c ---------------------------------------------------------------------
|
||
@node Binary files
|
||
@chapter Handling binary files
|
||
@cindex Binary files
|
||
|
||
There are two issues with using @sc{cvs} to store
|
||
binary files. The first is that @sc{cvs} by default
|
||
convert line endings between the canonical form in
|
||
which they are stored in the repository (linefeed
|
||
only), and the form appropriate to the operating system
|
||
in use on the client (for example, carriage return
|
||
followed by line feed for Windows NT).
|
||
|
||
The second is that a binary file might happen to
|
||
contain data which looks like a keyword (@pxref{Keyword
|
||
substitution}), so keyword expansion must be turned
|
||
off.
|
||
|
||
@c FIXME: the third is that one can't do merges with
|
||
@c binary files. xref to Multiple Developers and the
|
||
@c reserved checkout issues.
|
||
|
||
The @samp{-kb} option available with some @sc{cvs}
|
||
commands insures that neither line ending conversion
|
||
nor keyword expansion will be done. If you are using
|
||
an old version of @sc{rcs} without this option, and you
|
||
are using an operating system, such as unix, which
|
||
terminates lines with linefeeds only, you can use
|
||
@samp{-ko} instead; if you are on another operating
|
||
system, upgrade to a version of @sc{rcs}, such as 5.7
|
||
or later, which supports @samp{-kb}.
|
||
|
||
Here is an example of how you can create a new file
|
||
using the @samp{-kb} flag:
|
||
|
||
@example
|
||
$ echo '$@asis{}Id$' > kotest
|
||
$ cvs add -kb -m"A test file" kotest
|
||
$ cvs ci -m"First checkin; contains a keyword" kotest
|
||
@end example
|
||
|
||
If a file accidentally gets added without @samp{-kb},
|
||
one can use the @code{cvs admin} command to recover.
|
||
For example:
|
||
|
||
@example
|
||
$ echo '$@asis{}Id$' > kotest
|
||
$ cvs add -m"A test file" kotest
|
||
$ cvs ci -m"First checkin; contains a keyword" kotest
|
||
$ cvs admin -kb kotest
|
||
$ cvs update -A kotest
|
||
$ cvs commit -m "make it binary" kotest # @r{For non-unix systems}
|
||
@end example
|
||
|
||
When you check in the file @file{kotest} the keywords
|
||
are expanded. (Try the above example, and do a
|
||
@code{cat kotest} after every command). The @code{cvs
|
||
admin -kb} command sets the default keyword
|
||
substitution method for this file, but it does not
|
||
alter the working copy of the file that you have. The
|
||
easiest way to get the unexpanded version of
|
||
@file{kotest} is @code{cvs update -A}. If you need to
|
||
cope with line endings (that is, you are using a
|
||
@sc{cvs} client on a non-unix system), then you need to
|
||
check in a new copy of the file, as shown by the
|
||
@code{cvs commit} command above.
|
||
@c FIXME: should also describe what the *other users*
|
||
@c need to do, if they have checked out copies which
|
||
@c have been corrupted by lack of -kb. I think maybe
|
||
@c "cvs update -kb" or "cvs
|
||
@c update -A" would suffice, although the user who
|
||
@c reported this suggested removing the file, manually
|
||
@c removing it from CVS/Entries, and then "cvs update"
|
||
|
||
However, in using @code{cvs admin -k} to change the
|
||
keyword expansion, be aware that the keyword expansion
|
||
mode is not version controlled. This means that, for
|
||
example, that if you have a text file in old releases,
|
||
and a binary file with the same name in new releases,
|
||
@sc{cvs} provides no way to check out the file in text
|
||
or binary mode depending on what version you are
|
||
checking out. There is no good workaround for this
|
||
problem.
|
||
|
||
You can also set a default for whether @code{cvs add}
|
||
and @code{cvs import} treat a file as binary based on
|
||
its name; for example you could say that files who
|
||
names end in @samp{.exe} are binary. @xref{Wrappers}.
|
||
There is currently no way to have @sc{cvs} detect
|
||
whether a file is binary based on its contents. The
|
||
main difficulty with designing such a feature is that
|
||
it is not clear how to distinguish between binary and
|
||
non-binary files, and the rules to apply would vary
|
||
considerably with the operating system.
|
||
@c For example, it would be good on MS-DOS-family OSes
|
||
@c for anything containing ^Z to be binary. Having
|
||
@c characters with the 8th bit set imply binary is almost
|
||
@c surely a bad idea in the context of ISO-8859-* and
|
||
@c other such character sets. On VMS or the Mac, we
|
||
@c could use the OS's file typing. This is a
|
||
@c commonly-desired feature, and something of this sort
|
||
@c may make sense. But there are a lot of pitfalls here.
|
||
|
||
@c I'm not sure about the best location for this. In
|
||
@c one sense, it might belong right after we've introduced
|
||
@c CVS's basic version control model, because people need
|
||
@c to figure out builds right away. The current location
|
||
@c is based on the theory that it kind of akin to the
|
||
@c "Revision management" section.
|
||
@node Builds
|
||
@chapter How your build system interacts with CVS
|
||
@cindex builds
|
||
@cindex make
|
||
|
||
As mentioned in the introduction, @sc{cvs} does not
|
||
contain software for building your software from source
|
||
code. This section describes how various aspects of
|
||
your build system might interact with @sc{cvs}.
|
||
|
||
@c Is there a way to discuss this without reference to
|
||
@c tools other than CVS? I'm not sure there is; I
|
||
@c wouldn't think that people who learn CVS first would
|
||
@c even have this concern.
|
||
One common question, especially from people who are
|
||
accustomed to @sc{rcs}, is how to make their build get
|
||
an up to date copy of the sources. The answer to this
|
||
with @sc{cvs} is two-fold. First of all, since
|
||
@sc{cvs} itself can recurse through directories, there
|
||
is no need to modify your @file{Makefile} (or whatever
|
||
configuration file your build tool uses) to make sure
|
||
each file is up to date. Instead, just use two
|
||
commands, first @code{cvs -q update} and then
|
||
@code{make} or whatever the command is to invoke your
|
||
build tool. Secondly, you do not necessarily
|
||
@emph{want} to get a copy of a change someone else made
|
||
until you have finished your own work. One suggested
|
||
approach is to first update your sources, then
|
||
implement, build and
|
||
test the change you were thinking of, and then commit
|
||
your sources (updating first if necessary). By
|
||
periodically (in between changes, using the approach
|
||
just described) updating your entire tree, you ensure
|
||
that your sources are sufficiently up to date.
|
||
|
||
@cindex bill of materials
|
||
One common need is to record which versions of which
|
||
source files went into a particular build. This kind
|
||
of functionality is sometimes called @dfn{bill of
|
||
materials} or something similar. The best way to do
|
||
this with @sc{cvs} is to use the @code{tag} command to
|
||
record which versions went into a given build
|
||
(@pxref{Tags}).
|
||
|
||
Using @sc{cvs} in the most straightforward manner
|
||
possible, each developer will have a copy of the entire
|
||
source tree which is used in a particular build. If
|
||
the source tree is small, or if developers are
|
||
geographically dispersed, this is the preferred
|
||
solution. In fact one approach for larger projects is
|
||
to break a project down into smaller
|
||
@c I say subsystem instead of module because they may or
|
||
@c may not use the modules file.
|
||
separately-compiled subsystems, and arrange a way of
|
||
releasing them internally so that each developer need
|
||
check out only those subsystems which are they are
|
||
actively working on.
|
||
|
||
Another approach is to set up a structure which allows
|
||
developers to have their own copies of some files, and
|
||
for other files to access source files from a central
|
||
location. Many people have come up with some such a
|
||
@c two such people are paul@sander.cupertino.ca.us (for
|
||
@c a previous employer)
|
||
@c and gtornblo@senet.abb.se (spicm and related tools),
|
||
@c but as far as I know
|
||
@c noone has nicely packaged or released such a system (or
|
||
@c instructions for constructing one).
|
||
system using features such as the symbolic link feature
|
||
found in many operating systems, or the @code{VPATH}
|
||
feature found in many versions of @code{make}. One build
|
||
tool which is designed to help with this kind of thing
|
||
is Odin (see
|
||
@code{ftp://ftp.cs.colorado.edu/pub/distribs/odin}).
|
||
@c Should we be saying more about Odin? Or how you use
|
||
@c it with CVS? Also, the Prime Time Freeware for Unix
|
||
@c disk (see http://www.ptf.com/) has Odin (with a nice
|
||
@c paragraph summarizing it on the web), so that might be a
|
||
@c semi-"official" place to point people.
|
||
@c
|
||
@c Of course, many non-CVS systems have this kind of
|
||
@c functionality, for example OSF's ODE
|
||
@c (http://www.osf.org/ode/) or mk
|
||
@c (http://www.io.org/~pzi/heading.html;
|
||
@c ftp://ftp.interlog.com/pub/unix/mk is out of date). But I'm not sure
|
||
@c there is any point in mentioning them here unless they
|
||
@c can work with CVS.
|
||
|
||
@node Compatibility
|
||
@chapter Compatibility between CVS Versions
|
||
|
||
@cindex CVS, versions of
|
||
@cindex versions, of CVS
|
||
@cindex compatibility, between CVS versions
|
||
@c We don't mention versions older than CVS 1.3
|
||
@c on the theory that it would clutter it up for the vast
|
||
@c majority of people, who don't have anything that old.
|
||
@c
|
||
The repository format is compatible going back to
|
||
@sc{cvs} 1.3. But see @ref{Watches Compatibility}, if
|
||
you have copies of @sc{cvs} 1.6 or older and you want
|
||
to use the optional developer communication features.
|
||
@c If you "cvs rm" and commit using 1.3, then you'll
|
||
@c want to run "rcs -sdead <file,v>" on each of the
|
||
@c files in the Attic if you then want 1.5 and
|
||
@c later to recognize those files as dead (I think the
|
||
@c symptom if this is not done is that files reappear
|
||
@c in joins). (Wait: the above will work but really to
|
||
@c be strictly correct we should suggest checking
|
||
@c in a new revision rather than just changing the
|
||
@c state of the head revision, shouldn't we?).
|
||
@c The old convert.sh script was for this, but it never
|
||
@c did get updated to reflect use of the RCS "dead"
|
||
@c state.
|
||
@c Note: this is tricky to document without confusing
|
||
@c people--need to carefully say what CVS version we
|
||
@c are talking about and keep in mind the distinction
|
||
@c between a
|
||
@c repository created with 1.3 and on which one now
|
||
@c uses 1.5+, and a repository on which one wants to
|
||
@c use both versions side by side (e.g. during a
|
||
@c transition period).
|
||
@c We might want to separate out the 1.3 compatibility
|
||
@c section (for repository & working directory) from the
|
||
@c rest--that might help avoid confusing people who
|
||
@c are upgrading (for example) from 1.6 to 1.8.
|
||
@c
|
||
@c A minor incompatibility is if a current version of CVS
|
||
@c puts "Nfoo" into CVS/Tag, then CVS 1.9 or older will
|
||
@c see this as if there is no tag. Seems to me this is
|
||
@c too obscure to mention.
|
||
|
||
The working directory format is compatible going back
|
||
to @sc{cvs} 1.5. It did change between @sc{cvs} 1.3
|
||
and @sc{cvs} 1.5. If you run @sc{cvs} 1.5 or newer on
|
||
a working directory checked out with @sc{cvs} 1.3,
|
||
@sc{cvs} will convert it, but to go back to @sc{cvs}
|
||
1.3 you need to check out a new working directory with
|
||
@sc{cvs} 1.3.
|
||
|
||
The remote protocol is interoperable going back to @sc{cvs} 1.5, but no
|
||
further (1.5 was the first official release with the remote protocol,
|
||
but some older versions might still be floating around). In many
|
||
cases you need to upgrade both the client and the server to take
|
||
advantage of new features and bugfixes, however.
|
||
|
||
@c Perhaps should be saying something here about the
|
||
@c "D" lines in Entries (written by CVS 1.9; 1.8 and
|
||
@c older don't use them). These are supposed to be
|
||
@c compatible in both directions, but I'm not sure
|
||
@c they quite are 100%. One common gripe is if you
|
||
@c "rm -r" a directory and 1.9 gets confused, as it
|
||
@c still sees it in Entries. That one is fixed in
|
||
@c (say) 1.9.6. Someone else reported problems with
|
||
@c starting with a directory which was checked out with
|
||
@c an old version, and then using a new version, and
|
||
@c some "D" lines appeared, but not for every
|
||
@c directory, causing some directories to be skipped.
|
||
@c They weren't sure how to reproduce this, though.
|
||
|
||
@c ---------------------------------------------------------------------
|
||
@node Revision management
|
||
@chapter Revision management
|
||
@cindex Revision management
|
||
|
||
@c -- This chapter could be expanded a lot.
|
||
@c -- Experiences are very welcome!
|
||
|
||
If you have read this far, you probably have a pretty
|
||
good grasp on what @sc{cvs} can do for you. This
|
||
chapter talks a little about things that you still have
|
||
to decide.
|
||
|
||
If you are doing development on your own using @sc{cvs}
|
||
you could probably skip this chapter. The questions
|
||
this chapter takes up become more important when more
|
||
than one person is working in a repository.
|
||
|
||
@menu
|
||
* When to commit:: Some discussion on the subject
|
||
@end menu
|
||
|
||
@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
|
||
@node When to commit
|
||
@section When to commit?
|
||
@cindex When to commit
|
||
@cindex Commit, when to
|
||
@cindex Policy
|
||
|
||
Your group should decide which policy to use regarding
|
||
commits. Several policies are possible, and as your
|
||
experience with @sc{cvs} grows you will probably find
|
||
out what works for you.
|
||
|
||
If you commit files too quickly you might commit files
|
||
that do not even compile. If your partner updates his
|
||
working sources to include your buggy file, he will be
|
||
unable to compile the code. On the other hand, other
|
||
persons will not be able to benefit from the
|
||
improvements you make to the code if you commit very
|
||
seldom, and conflicts will probably be more common.
|
||
|
||
It is common to only commit files after making sure
|
||
that they can be compiled. Some sites require that the
|
||
files pass a test suite. Policies like this can be
|
||
enforced using the commitinfo file
|
||
(@pxref{commitinfo}), but you should think twice before
|
||
you enforce such a convention. By making the
|
||
development environment too controlled it might become
|
||
too regimented and thus counter-productive to the real
|
||
goal, which is to get software written.
|
||
|
||
@c ---------------------------------------------------------------------
|
||
@node CVS commands
|
||
@appendix Guide to CVS commands
|
||
|
||
This appendix describes the overall structure of
|
||
@sc{cvs} commands, and describes some commands in
|
||
detail (others are described elsewhere; for a quick
|
||
reference to @sc{cvs} commands, @pxref{Invoking CVS}).
|
||
@c The idea is that we want to move the commands which
|
||
@c are described here into the main body of the manual,
|
||
@c in the process reorganizing the manual to be
|
||
@c organized around what the user wants to do, not
|
||
@c organized around CVS commands.
|
||
|
||
@menu
|
||
* Structure:: Overall structure of CVS commands
|
||
* Exit status:: Indicating CVS's success or failure
|
||
* ~/.cvsrc:: Default options with the ~/.csvrc file
|
||
* Global options:: Options you give to the left of cvs_command
|
||
* Common options:: Options you give to the right of cvs_command
|
||
* admin:: Administration front end for rcs
|
||
* checkout:: Checkout sources for editing
|
||
* commit:: Check files into the repository
|
||
* diff:: Show differences between revisions
|
||
* export:: Export sources from CVS, similar to checkout
|
||
* history:: Show status of files and users
|
||
* import:: Import sources into CVS, using vendor branches
|
||
* log:: Show log messages for files
|
||
* rdiff:: 'patch' format diffs between releases
|
||
* release:: Indicate that a Module is no longer in use
|
||
* rtag:: Add a tag to a module
|
||
* tag:: Add a tag to checked out version
|
||
* update:: Bring work tree in sync with repository
|
||
@end menu
|
||
|
||
@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
|
||
@node Structure
|
||
@appendixsec Overall structure of CVS commands
|
||
@cindex Structure
|
||
@cindex CVS command structure
|
||
@cindex Command structure
|
||
@cindex Format of CVS commands
|
||
|
||
The overall format of all @sc{cvs} commands is:
|
||
|
||
@example
|
||
cvs [ cvs_options ] cvs_command [ command_options ] [ command_args ]
|
||
@end example
|
||
|
||
@table @code
|
||
@item cvs
|
||
The name of the @sc{cvs} program.
|
||
|
||
@item cvs_options
|
||
Some options that affect all sub-commands of @sc{cvs}. These are
|
||
described below.
|
||
|
||
@item cvs_command
|
||
One of several different sub-commands. Some of the commands have
|
||
aliases that can be used instead; those aliases are noted in the
|
||
reference manual for that command. There are only two situations
|
||
where you may omit @samp{cvs_command}: @samp{cvs -H} elicits a
|
||
list of available commands, and @samp{cvs -v} displays version
|
||
information on @sc{cvs} itself.
|
||
|
||
@item command_options
|
||
Options that are specific for the command.
|
||
|
||
@item command_args
|
||
Arguments to the commands.
|
||
@end table
|
||
|
||
There is unfortunately some confusion between
|
||
@code{cvs_options} and @code{command_options}.
|
||
@samp{-l}, when given as a @code{cvs_option}, only
|
||
affects some of the commands. When it is given as a
|
||
@code{command_option} is has a different meaning, and
|
||
is accepted by more commands. In other words, do not
|
||
take the above categorization too seriously. Look at
|
||
the documentation instead.
|
||
|
||
@node Exit status
|
||
@appendixsec CVS's exit status
|
||
@cindex exit status, of CVS
|
||
|
||
CVS can indicate to the calling environment whether it
|
||
succeeded or failed by setting its @dfn{exit status}.
|
||
The exact way of testing the exit status will vary from
|
||
one operating system to another. For example in a unix
|
||
shell script the @samp{$?} variable will be 0 if the
|
||
last command returned a successful exit status, or
|
||
greater than 0 if the exit status indicated failure.
|
||
|
||
If CVS is successful, it returns a successful status;
|
||
if there is an error, it prints an error message and
|
||
returns a failure status. The one exception to this is
|
||
the @code{cvs diff} command. It will return a
|
||
successful status if it found no differences, or a
|
||
failure status if there were differences or if there
|
||
was an error. Because this behavior provides no good
|
||
way to detect errors, in the future it is possible that
|
||
@code{cvs diff} will be changed to behave like the
|
||
other @sc{cvs} commands.
|
||
@c It might seem like checking whether cvs -q diff
|
||
@c produces empty or non-empty output can tell whether
|
||
@c there were differences or not. But it seems like
|
||
@c there are cases with output but no differences
|
||
@c (testsuite basica-8b). It is not clear to me how
|
||
@c useful it is for a script to be able to check
|
||
@c whether there were differences.
|
||
@c FIXCVS? In previous versions of CVS, cvs diff
|
||
@c returned 0 for no differences, 1 for differences, or
|
||
@c 2 for errors. Is this behavior worth trying to
|
||
@c bring back (but what does it mean for VMS?)?
|
||
|
||
@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
|
||
@node ~/.cvsrc
|
||
@appendixsec Default options and the ~/.cvsrc file
|
||
@cindex .cvsrc file
|
||
@cindex option defaults
|
||
|
||
There are some @code{command_options} that are used so
|
||
often that you might have set up an alias or some other
|
||
means to make sure you always specify that option. One
|
||
example (the one that drove the implementation of the
|
||
.cvsrc support, actually) is that many people find the
|
||
default output of the @samp{diff} command to be very
|
||
hard to read, and that either context diffs or unidiffs
|
||
are much easier to understand.
|
||
|
||
The @file{~/.cvsrc} file is a way that you can add
|
||
default options to @code{cvs_commands} within cvs,
|
||
instead of relying on aliases or other shell scripts.
|
||
|
||
The format of the @file{~/.cvsrc} file is simple. The
|
||
file is searched for a line that begins with the same
|
||
name as the @code{cvs_command} being executed. If a
|
||
match is found, then the remainder of the line is split
|
||
up (at whitespace characters) into separate options and
|
||
added to the command arguments @emph{before} any
|
||
options from the command line.
|
||
|
||
If a command has two names (e.g., @code{checkout} and
|
||
@code{co}), the official name, not necessarily the one
|
||
used on the command line, will be used to match against
|
||
the file. So if this is the contents of the user's
|
||
@file{~/.cvsrc} file:
|
||
|
||
@example
|
||
log -N
|
||
diff -u
|
||
update -P
|
||
co -P
|
||
@end example
|
||
|
||
@noindent
|
||
the command @samp{cvs checkout foo} would have the
|
||
@samp{-P} option added to the arguments, as well as
|
||
@samp{cvs co foo}.
|
||
|
||
With the example file above, the output from @samp{cvs
|
||
diff foobar} will be in unidiff format. @samp{cvs diff
|
||
-c foobar} will provide context diffs, as usual.
|
||
Getting "old" format diffs would be slightly more
|
||
complicated, because @code{diff} doesn't have an option
|
||
to specify use of the "old" format, so you would need
|
||
@samp{cvs -f diff foobar}.
|
||
|
||
In place of the command name you can use @code{cvs} to
|
||
specify global options (@pxref{Global options}). For
|
||
example the following line in @file{.cvsrc}
|
||
|
||
@example
|
||
cvs -z6
|
||
@end example
|
||
|
||
causes @sc{cvs} to use compression level 6
|
||
|
||
@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
|
||
@node Global options
|
||
@appendixsec Global options
|
||
@cindex Options, global
|
||
@cindex Global options
|
||
@cindex Left-hand options
|
||
|
||
The available @samp{cvs_options} (that are given to the
|
||
left of @samp{cvs_command}) are:
|
||
|
||
@table @code
|
||
@cindex RCSBIN, overriding
|
||
@cindex Overriding RCSBIN
|
||
@item -b @var{bindir}
|
||
Use @var{bindir} as the directory where @sc{rcs} programs are
|
||
located. Overrides the setting of the @code{$RCSBIN} environment
|
||
variable and any precompiled directory. This parameter should be
|
||
specified as an absolute pathname.
|
||
|
||
@cindex TMPDIR, overriding
|
||
@cindex Overriding TMPDIR
|
||
@item -T @var{tempdir}
|
||
Use @var{tempdir} as the directory where temporary files are
|
||
located. Overrides the setting of the @code{$TMPDIR} environment
|
||
variable and any precompiled directory. This parameter should be
|
||
specified as an absolute pathname.
|
||
|
||
@cindex CVSROOT, overriding
|
||
@cindex Overriding CVSROOT
|
||
@item -d @var{cvs_root_directory}
|
||
Use @var{cvs_root_directory} as the root directory
|
||
pathname of the repository. Overrides the setting of
|
||
the @code{$CVSROOT} environment variable. @xref{Repository}.
|
||
|
||
@cindex EDITOR, overriding
|
||
@cindex Overriding EDITOR
|
||
@item -e @var{editor}
|
||
Use @var{editor} to enter revision log information. Overrides the
|
||
setting of the @code{$CVSEDITOR} and @code{$EDITOR}
|
||
environment variables. For more information, see
|
||
@ref{Committing your changes}.
|
||
|
||
@item -f
|
||
Do not read the @file{~/.cvsrc} file. This
|
||
option is most often used because of the
|
||
non-orthogonality of the @sc{cvs} option set. For
|
||
example, the @samp{cvs log} option @samp{-N} (turn off
|
||
display of tag names) does not have a corresponding
|
||
option to turn the display on. So if you have
|
||
@samp{-N} in the @file{~/.cvsrc} entry for @samp{log},
|
||
you may need to use @samp{-f} to show the tag names.
|
||
|
||
@item -H
|
||
@itemx --help
|
||
Display usage information about the specified @samp{cvs_command}
|
||
(but do not actually execute the command). If you don't specify
|
||
a command name, @samp{cvs -H} displays overall help for
|
||
@sc{cvs}, including a list of other help options.
|
||
@c It seems to me it is better to document it this way
|
||
@c rather than trying to update this documentation
|
||
@c every time that we add a --help-foo option. But
|
||
@c perhaps that is confusing...
|
||
|
||
@item -l
|
||
Do not log the cvs_command in the command history (but execute it
|
||
anyway). @xref{history}, for information on command history.
|
||
|
||
@cindex Read-only mode
|
||
@item -n
|
||
Do not change any files. Attempt to execute the
|
||
@samp{cvs_command}, but only to issue reports; do not remove,
|
||
update, or merge any existing files, or create any new files.
|
||
|
||
@item -Q
|
||
Cause the command to be really quiet; the command will only
|
||
generate output for serious problems.
|
||
|
||
@item -q
|
||
Cause the command to be somewhat quiet; informational messages,
|
||
such as reports of recursion through subdirectories, are
|
||
suppressed.
|
||
|
||
@cindex read-only files, and -r
|
||
@item -r
|
||
Make new working files files read-only. Same effect
|
||
as if the @code{$CVSREAD} environment variable is set
|
||
(@pxref{Environment variables}). The default is to
|
||
make working files writable, unless watches are on
|
||
(@pxref{Watches}).
|
||
|
||
@item -s @var{variable}=@var{value}
|
||
Set a user variable (@pxref{Variables}).
|
||
|
||
@cindex Trace
|
||
@item -t
|
||
Trace program execution; display messages showing the steps of
|
||
@sc{cvs} activity. Particularly useful with @samp{-n} to explore the
|
||
potential impact of an unfamiliar command.
|
||
|
||
@item -v
|
||
@item --version
|
||
Display version and copyright information for @sc{cvs}.
|
||
|
||
@cindex CVSREAD, overriding
|
||
@cindex Overriding CVSREAD
|
||
@item -w
|
||
Make new working files read-write. Overrides the
|
||
setting of the @code{$CVSREAD} environment variable.
|
||
Files are created read-write by default, unless @code{$CVSREAD} is
|
||
set or @samp{-r} is given.
|
||
|
||
@item -x
|
||
Encrypt all communication between the client and the
|
||
server. Only has an effect on the @sc{cvs} client. As
|
||
of this writing, this is only implemented when using a
|
||
Kerberos connection (@pxref{Kerberos authenticated}).
|
||
Encryption support is not available by default; it must
|
||
be enabled using a special configure option,
|
||
@file{--enable-encryption}, when you build @sc{cvs}.
|
||
|
||
@item -z @var{gzip-level}
|
||
Set the compression level. Only has an effect on the
|
||
@sc{cvs} client.
|
||
|
||
@end table
|
||
|
||
@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
|
||
@node Common options
|
||
@appendixsec Common command options
|
||
@cindex Common options
|
||
@cindex Right-hand options
|
||
|
||
This section describes the @samp{command_options} that
|
||
are available across several @sc{cvs} commands. These
|
||
options are always given to the right of
|
||
@samp{cvs_command}. Not all
|
||
commands support all of these options; each option is
|
||
only supported for commands where it makes sense.
|
||
However, when a command has one of these options you
|
||
can almost always count on the same behavior of the
|
||
option as in other commands. (Other command options,
|
||
which are listed with the individual commands, may have
|
||
different behavior from one @sc{cvs} command to the other).
|
||
|
||
@strong{Warning:} the @samp{history} command is an exception; it supports
|
||
many options that conflict even with these standard options.
|
||
|
||
@table @code
|
||
@cindex Dates
|
||
@cindex Time
|
||
@cindex Specifying dates
|
||
@item -D @var{date_spec}
|
||
Use the most recent revision no later than @var{date_spec}.
|
||
@var{date_spec} is a single argument, a date description
|
||
specifying a date in the past.
|
||
|
||
The specification is @dfn{sticky} when you use it to make a
|
||
private copy of a source file; that is, when you get a working
|
||
file using @samp{-D}, @sc{cvs} records the date you specified, so that
|
||
further updates in the same directory will use the same date
|
||
(for more information on sticky tags/dates, @pxref{Sticky tags}).
|
||
|
||
@samp{-D} is available with the @code{checkout},
|
||
@code{diff}, @code{export}, @code{history},
|
||
@code{rdiff}, @code{rtag}, and @code{update} commands.
|
||
(The @code{history} command uses this option in a
|
||
slightly different way; @pxref{history options}).
|
||
|
||
@c What other formats should we accept? I don't want
|
||
@c to start accepting a whole mess of non-standard
|
||
@c new formats (there are a lot which are in wide use in
|
||
@c one context or another), but practicality does
|
||
@c dictate some level of flexibility.
|
||
@c * POSIX.2 (e.g. touch, ls output, date) and other
|
||
@c POSIX and/or de facto unix standards (e.g. at). The
|
||
@c practice here is too inconsistent to be of any use.
|
||
@c * VMS dates. This is not a formal standard, but
|
||
@c there is a published specification (see SYS$ASCTIM
|
||
@c and SYS$BINTIM in the _VMS System Services Reference
|
||
@c Manual_), it is implemented consistently in VMS
|
||
@c utilities, and VMS users will expect CVS running on
|
||
@c VMS to support this format (and if we're going to do
|
||
@c that, better to make CVS support it on all
|
||
@c platforms. Maybe).
|
||
@c
|
||
@c NOTE: The tar manual has some documentation for
|
||
@c getdate.y (just for our info; we don't want to
|
||
@c attempt to document all the formats accepted by
|
||
@c getdate.y).
|
||
@c
|
||
@c One more note: In output, CVS should consistently
|
||
@c use one date format, and that format should be one that
|
||
@c it accepts in input as well. The former isn't
|
||
@c really true (see survey below), and I'm not
|
||
@c sure that either of those formats is accepted in
|
||
@c input.
|
||
@c
|
||
@c cvs log
|
||
@c current 1996/01/02 13:45:31
|
||
@c Internet 02 Jan 1996 13:45:31 UT
|
||
@c ISO 1996-01-02 13:45:31
|
||
@c cvs ann
|
||
@c current 02-Jan-96
|
||
@c Internet-like 02 Jan 96
|
||
@c ISO 96-01-02
|
||
@c cvs status
|
||
@c current Tue Jun 11 02:54:53 1996
|
||
@c Internet [Tue,] 11 Jun 1996 02:54:53
|
||
@c ISO 1996-06-11 02:54:53
|
||
@c note: date possibly should be omitted entirely for
|
||
@c other reasons.
|
||
@c cvs editors
|
||
@c current Tue Jun 11 02:54:53 1996 GMT
|
||
@c cvs history
|
||
@c current 06/11 02:54 +0000
|
||
@c any others?
|
||
@c There is a good chance the proper solution has to
|
||
@c involve at least some level of letting the user
|
||
@c decide which format (with the default being the
|
||
@c formats CVS has always used; changing these might be
|
||
@c _very_ disruptive since scripts may very well be
|
||
@c parsing them).
|
||
@c
|
||
@c Another random bit of prior art concerning dates is
|
||
@c the strptime function which takes templates such as
|
||
@c "%m/%d/%y", and apparent a variant of getdate()
|
||
@c which also honors them. See
|
||
@c X/Open CAE Specification, System Interfaces and
|
||
@c Headers Issue 4, Version 2 (September 1994), in the
|
||
@c entry for getdate() on page 231
|
||
|
||
@cindex timezone, in input
|
||
@cindex zone, time, in input
|
||
A wide variety of date formats are supported by
|
||
@sc{cvs}. The most standard ones are ISO8601 (from the
|
||
International Standards Organization) and the Internet
|
||
e-mail standard (specified in RFC822 as amended by
|
||
RFC1123).
|
||
|
||
@c Probably should be doing more to spell out just what
|
||
@c the rules are, rather than just giving examples.
|
||
@c But I want to keep this simple too.
|
||
@c So I don't know....
|
||
@c A few specific issues: (1) Maybe should reassure
|
||
@c people that years after 2000
|
||
@c work (they are in the testsuite, so they do indeed
|
||
@c work). (2) What do two digit years
|
||
@c mean? Where do we accept them? (3) Local times can
|
||
@c be ambiguous or nonexistent if they fall during the
|
||
@c hour when daylight savings time goes into or out of
|
||
@c effect. Pretty obscure, so I'm not at all sure we
|
||
@c should be documenting the behavior in that case.
|
||
ISO8601 dates have many variants but a few examples
|
||
are:
|
||
|
||
@example
|
||
1972-09-24
|
||
1972-09-24 20:05
|
||
@end example
|
||
@c I doubt we really accept all ISO8601 format dates
|
||
@c (for example, decimal hours like 1972-09-24 20,2)
|
||
@c I'm not sure we should, many of them are pretty
|
||
@c bizarre and it has lots of gratuitous multiple ways
|
||
@c to specify the same thing.
|
||
|
||
For more details about ISO8601 dates, see:
|
||
|
||
@example
|
||
http://www.ft.uni-erlangen.de/~mskuhn/iso-time.html
|
||
@end example
|
||
@c Perhaps we want to also cite other sources in
|
||
@c case that page goes away. For example:
|
||
@c http://www.saqqara.demon.co.uk/datefmt.htm
|
||
|
||
In addition to the dates allowed in Internet e-mail
|
||
itself, @sc{cvs} also allows some of the fields to be
|
||
omitted. For example:
|
||
@c FIXME: Need to figure out better, and document,
|
||
@c what we want to allow the user to omit.
|
||
@c NOTE: "omit" does not imply "reorder".
|
||
@c FIXME: Need to cite a web page describing how to get
|
||
@c RFC's.
|
||
|
||
@example
|
||
24 Sep 1972 20:05
|
||
24 Sep
|
||
@end example
|
||
|
||
The date is interpreted as being in the
|
||
local timezone, unless a specific timezone is
|
||
specified.
|
||
|
||
These two date formats are preferred. However,
|
||
@sc{cvs} currently accepts a wide variety of other date
|
||
formats. They are intentionally not documented here in
|
||
any detail, and future versions of @sc{cvs} might not
|
||
accept all of them.
|
||
@c Maybe at
|
||
@c some point have CVS start give warnings on "unofficial"
|
||
@c formats (many of which might be typos or user
|
||
@c misunderstandings, and/or formats people never/rarely
|
||
@c use to specify dates)?
|
||
|
||
One such format is
|
||
@code{@var{month}/@var{day}/@var{year}}. This may
|
||
confuse people who are accustomed to having the month
|
||
and day in the other order; @samp{1/4/96} is January 4,
|
||
not April 1.
|
||
|
||
Remember to quote the argument to the @samp{-D}
|
||
flag so that your shell doesn't interpret spaces as
|
||
argument separators. A command using the @samp{-D}
|
||
flag can look like this:
|
||
|
||
@example
|
||
$ cvs diff -D "1 hour ago" cvs.texinfo
|
||
@end example
|
||
|
||
@cindex Forcing a tag match
|
||
@item -f
|
||
When you specify a particular date or tag to @sc{cvs} commands, they
|
||
normally ignore files that do not contain the tag (or did not
|
||
exist prior to the date) that you specified. Use the @samp{-f} option
|
||
if you want files retrieved even when there is no match for the
|
||
tag or date. (The most recent revision of the file
|
||
will be used).
|
||
|
||
@need 800
|
||
@samp{-f} is available with these commands:
|
||
@code{annotate}, @code{checkout}, @code{export},
|
||
@code{rdiff}, @code{rtag}, and @code{update}.
|
||
|
||
@strong{Warning:} The @code{commit} command also has a
|
||
@samp{-f} option, but it has a different behavior for
|
||
that command. @xref{commit options}.
|
||
|
||
@item -k @var{kflag}
|
||
Alter the default @sc{rcs} processing of keywords.
|
||
@xref{Keyword substitution}, for the meaning of
|
||
@var{kflag}. Your @var{kflag} specification is
|
||
@dfn{sticky} when you use it to create a private copy
|
||
of a source file; that is, when you use this option
|
||
with the @code{checkout} or @code{update} commands,
|
||
@sc{cvs} associates your selected @var{kflag} with the
|
||
file, and continues to use it with future update
|
||
commands on the same file until you specify otherwise.
|
||
|
||
The @samp{-k} option is available with the @code{add},
|
||
@code{checkout}, @code{diff}, @code{import} and
|
||
@code{update} commands.
|
||
|
||
@item -l
|
||
Local; run only in current working directory, rather than
|
||
recursing through subdirectories.
|
||
|
||
@strong{Warning:} this is not the same
|
||
as the overall @samp{cvs -l} option, which you can specify to the
|
||
left of a cvs command!
|
||
|
||
Available with the following commands: @code{annotate}, @code{checkout},
|
||
@code{commit}, @code{diff}, @code{edit}, @code{editors}, @code{export},
|
||
@code{log}, @code{rdiff}, @code{remove}, @code{rtag},
|
||
@code{status}, @code{tag}, @code{unedit}, @code{update}, @code{watch},
|
||
and @code{watchers}.
|
||
|
||
@cindex Editor, avoiding invocation of
|
||
@cindex Avoiding editor invocation
|
||
@item -m @var{message}
|
||
Use @var{message} as log information, instead of
|
||
invoking an editor.
|
||
|
||
Available with the following commands: @code{add},
|
||
@code{commit} and @code{import}.
|
||
|
||
@item -n
|
||
Do not run any checkout/commit/tag program. (A program can be
|
||
specified to run on each of these activities, in the modules
|
||
database (@pxref{modules}); this option bypasses it).
|
||
|
||
@strong{Warning:} this is not the same as the overall @samp{cvs -n}
|
||
option, which you can specify to the left of a cvs command!
|
||
|
||
Available with the @code{checkout}, @code{commit}, @code{export},
|
||
and @code{rtag} commands.
|
||
|
||
@item -P
|
||
Prune empty directories. See @xref{Removing directories}.
|
||
|
||
@item -p
|
||
Pipe the files retrieved from the repository to standard output,
|
||
rather than writing them in the current directory. Available
|
||
with the @code{checkout} and @code{update} commands.
|
||
|
||
@item -R
|
||
Process directories recursively. This is on by default.
|
||
|
||
Available with the following commands: @code{annotate}, @code{checkout},
|
||
@code{commit}, @code{diff}, @code{edit}, @code{editors}, @code{export},
|
||
@code{rdiff}, @code{remove}, @code{rtag},
|
||
@code{status}, @code{tag}, @code{unedit}, @code{update}, @code{watch},
|
||
and @code{watchers}.
|
||
|
||
@item -r @var{tag}
|
||
Use the revision specified by the @var{tag} argument instead of the
|
||
default @dfn{head} revision. As well as arbitrary tags defined
|
||
with the @code{tag} or @code{rtag} command, two special tags are
|
||
always available: @samp{HEAD} refers to the most recent version
|
||
available in the repository, and @samp{BASE} refers to the
|
||
revision you last checked out into the current working directory.
|
||
|
||
@c FIXME: What does HEAD really mean? I believe that
|
||
@c the current answer is the head of the default branch
|
||
@c for all cvs commands except diff. For diff, it
|
||
@c seems to be (a) the head of the trunk (or the default
|
||
@c branch?) if there is no sticky tag, (b) the head of the
|
||
@c branch if there is a branch sticky tag, and (c) the
|
||
@c same as BASE if there is a non-branch sticky tag. (c)
|
||
@c would appear to be strange, maybe accidental, and so there would
|
||
@c presumably be
|
||
@c little problem changing it. (b) is ugly as it differs
|
||
@c from what HEAD means for other commands, but people
|
||
@c might be used to it (note a change in NEWS? Or provide
|
||
@c advance warning of it changing?) and possible useful
|
||
@c (could be fixed by a new tag ".bhead" which would mean
|
||
@c the head of the appropriate branch). This
|
||
@c should be investigated, test cases written, and
|
||
@c documented (but HEAD should mean the same thing for all
|
||
@c CVS commands, so I don't know if we should be
|
||
@c documenting the current "cvs diff" behavior).
|
||
|
||
The tag specification is sticky when you use this
|
||
@c option
|
||
with @code{checkout} or @code{update} to make your own
|
||
copy of a file: @sc{cvs} remembers the tag and continues to use it on
|
||
future update commands, until you specify otherwise (for more information
|
||
on sticky tags/dates, @pxref{Sticky tags}). The
|
||
tag can be either a symbolic or numeric tag.
|
||
@xref{Tags}.
|
||
|
||
Specifying the @samp{-q} global option along with the
|
||
@samp{-r} command option is often useful, to suppress
|
||
the warning messages when the @sc{rcs} history file
|
||
does not contain the specified tag.
|
||
|
||
@strong{Warning:} this is not the same as the overall `cvs -r' option,
|
||
which you can specify to the left of a cvs command!
|
||
|
||
@samp{-r} is available with the @code{checkout}, @code{commit},
|
||
@code{diff}, @code{history}, @code{export}, @code{rdiff},
|
||
@code{rtag}, and @code{update} commands.
|
||
|
||
@item -W
|
||
Specify file names that should be filtered. You can
|
||
use this option repeatedly. The spec can be a file
|
||
name pattern of the same type that you can specify in
|
||
the @file{.cvswrappers} file.
|
||
Avaliable with the following commands: @code{import},
|
||
and @code{update}.
|
||
|
||
@end table
|
||
|
||
@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
|
||
@node admin
|
||
@appendixsec admin---Administration front end for rcs
|
||
@cindex Admin (subcommand)
|
||
|
||
@itemize @bullet
|
||
@item
|
||
Requires: repository, working directory.
|
||
@item
|
||
Changes: repository.
|
||
@item
|
||
Synonym: rcs
|
||
@end itemize
|
||
|
||
This is the @sc{cvs} interface to assorted administrative @sc{rcs}
|
||
facilities, documented in rcs(1). @code{admin} simply passes
|
||
all its options and arguments to the @code{rcs} command; it does
|
||
no filtering or other processing. This command @emph{does} work
|
||
recursively, however, so extreme care should be used.
|
||
|
||
@c "group" should probably read "unix group" (but what
|
||
@c does NT local do?). "compiled in value" is
|
||
@c unclear--compiled in to what?
|
||
If there is a group whose name matches a compiled in
|
||
value which defaults to @code{cvsadmin}, only members
|
||
of that group can use @code{cvs admin}. To disallow
|
||
@code{cvs admin} for all users, create a group with no
|
||
users in it.
|
||
|
||
@menu
|
||
* admin options:: admin options
|
||
* admin examples:: admin examples
|
||
@end menu
|
||
|
||
@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
|
||
@node admin options
|
||
@appendixsubsec admin options
|
||
|
||
Not all valid @code{rcs} options are useful together
|
||
with @sc{cvs}. Some even makes it impossible to use
|
||
@sc{cvs} until you undo the effect!
|
||
|
||
This description of the available options is based on
|
||
the @samp{rcs(1)} man page, but modified to suit
|
||
readers that are more interested in @sc{cvs} than
|
||
@sc{rcs}.
|
||
|
||
@table @code
|
||
@item -A@var{oldfile}
|
||
Might not work together with @sc{cvs}. Append the
|
||
access list of @var{oldfile} to the access list of the
|
||
@sc{rcs} file.
|
||
|
||
@item -a@var{logins}
|
||
Might not work together with @sc{cvs}. Append the
|
||
login names appearing in the comma-separated list
|
||
@var{logins} to the access list of the @sc{rcs} file.
|
||
|
||
@item -b[@var{rev}]
|
||
When used with bare @sc{rcs}, this
|
||
option sets the default branch to @var{rev}; in
|
||
@sc{cvs} sticky tags (@pxref{Sticky tags}) are a better
|
||
way to decide which branch you want to work on. There
|
||
is one use with @sc{cvs}: to revert to the vendor's
|
||
version when using vendor branches (@pxref{Reverting
|
||
local changes}).
|
||
|
||
@item -c@var{string}
|
||
Useful with @sc{cvs}. Sets the comment leader to
|
||
@var{string}. The comment leader is printed before
|
||
every log message line generated by the keyword
|
||
@code{$@asis{}Log$} (@pxref{Keyword substitution}).
|
||
This is useful for programming languages without
|
||
multi-line comments. @sc{Rcs} initially guesses the
|
||
value of the comment leader from the file name
|
||
extension when the file is first committed.
|
||
|
||
@item -e[@var{logins}]
|
||
Might not work together with @sc{cvs}. Erase the login
|
||
names appearing in the comma-separated list
|
||
@var{logins} from the access list of the RCS file. If
|
||
@var{logins} is omitted, erase the entire access list.
|
||
|
||
@c FIXME: Doesn't work with client/server CVS; we
|
||
@c should probably just not accept the option.
|
||
@item -I
|
||
Run interactively, even if the standard input is not a
|
||
terminal.
|
||
|
||
@item -i
|
||
Useless with @sc{cvs}. When using bare @sc{rcs}, this
|
||
is used to create and initialize a new @sc{rcs} file,
|
||
without depositing a revision.
|
||
|
||
@item -k@var{subst}
|
||
Useful with @sc{cvs}. Set the default keyword
|
||
substitution to @var{subst}. @xref{Keyword
|
||
substitution}. Giving an explicit @samp{-k} option to
|
||
@code{cvs update}, @code{cvs export}, or @code{cvs
|
||
checkout} overrides this default.
|
||
|
||
@item -l[@var{rev}]
|
||
Lock the revision with number @var{rev}. If a branch
|
||
is given, lock the latest revision on that branch. If
|
||
@var{rev} is omitted, lock the latest revision on the
|
||
default branch.
|
||
|
||
This can be used in conjunction with the
|
||
@file{rcslock.pl} script in the @file{contrib}
|
||
directory of the @sc{cvs} source distribution to
|
||
provide reserved checkouts (where only one user can be
|
||
editing a given file at a time). See the comments in
|
||
that file for details (and see the @file{README} file
|
||
in that directory for disclaimers about the unsupported
|
||
nature of contrib). According to comments in that
|
||
file, locking must set to strict (which is the default).
|
||
|
||
@item -L
|
||
Set locking to strict. Strict locking means that the
|
||
owner of an RCS file is not exempt from locking for
|
||
checkin. For use with @sc{cvs}, strict locking must be
|
||
set; see the discussion under the @samp{-l} option above.
|
||
|
||
@cindex Changing a log message
|
||
@cindex Replacing a log message
|
||
@cindex Correcting a log message
|
||
@cindex Fixing a log message
|
||
@cindex Log message, correcting
|
||
@item -m@var{rev}:@var{msg}
|
||
Replace the log message of revision @var{rev} with
|
||
@var{msg}.
|
||
|
||
@item -N@var{name}[:[@var{rev}]]
|
||
Act like @samp{-n}, except override any previous
|
||
assignment of @var{name}.
|
||
|
||
@item -n@var{name}[:[@var{rev}]]
|
||
Associate the symbolic name @var{name} with the branch
|
||
or revision @var{rev}. It is normally better to use
|
||
@samp{cvs tag} or @samp{cvs rtag} instead. Delete the
|
||
symbolic name if both @samp{:} and @var{rev} are
|
||
omitted; otherwise, print an error message if
|
||
@var{name} is already associated with another number.
|
||
If @var{rev} is symbolic, it is expanded before
|
||
association. A @var{rev} consisting of a branch number
|
||
followed by a @samp{.} stands for the current latest
|
||
revision in the branch. A @samp{:} with an empty
|
||
@var{rev} stands for the current latest revision on the
|
||
default branch, normally the trunk. For example,
|
||
@samp{rcs -n@var{name}: RCS/*} associates @var{name} with the
|
||
current latest revision of all the named RCS files;
|
||
this contrasts with @samp{rcs -n@var{name}:$ RCS/*} which
|
||
associates @var{name} with the revision numbers
|
||
extracted from keyword strings in the corresponding
|
||
working files.
|
||
|
||
@cindex Deleting revisions
|
||
@cindex Outdating revisions
|
||
@cindex Saving space
|
||
@item -o@var{range}
|
||
Potentially useful, but dangerous, with @sc{cvs} (see below).
|
||
Deletes (@dfn{outdates}) the revisions given by
|
||
@var{range}. A range consisting of a single revision
|
||
number means that revision. A range consisting of a
|
||
branch number means the latest revision on that branch.
|
||
A range of the form @samp{@var{rev1}:@var{rev2}} means
|
||
revisions @var{rev1} to @var{rev2} on the same branch,
|
||
@samp{:@var{rev}} means from the beginning of the
|
||
branch containing @var{rev} up to and including
|
||
@var{rev}, and @samp{@var{rev}:} means from revision
|
||
@var{rev} to the end of the branch containing
|
||
@var{rev}. None of the outdated revisions may have
|
||
branches or locks.
|
||
|
||
Due to the way @sc{cvs} handles branches @var{rev}
|
||
cannot be specified symbolically if it is a branch.
|
||
@xref{Magic branch numbers}, for an explanation.
|
||
|
||
Make sure that no-one has checked out a copy of the
|
||
revision you outdate. Strange things will happen if he
|
||
starts to edit it and tries to check it back in. For
|
||
this reason, this option is not a good way to take back
|
||
a bogus commit; commit a new revision undoing the bogus
|
||
change instead (@pxref{Merging two revisions}).
|
||
|
||
@item -q
|
||
Run quietly; do not print diagnostics.
|
||
|
||
@item -s@var{state}[:@var{rev}]
|
||
Useful with @sc{cvs}. Set the state attribute of the
|
||
revision @var{rev} to @var{state}. If @var{rev} is a
|
||
branch number, assume the latest revision on that
|
||
branch. If @var{rev} is omitted, assume the latest
|
||
revision on the default branch. Any identifier is
|
||
acceptable for @var{state}. A useful set of states is
|
||
@samp{Exp} (for experimental), @samp{Stab} (for
|
||
stable), and @samp{Rel} (for released). By default,
|
||
the state of a new revision is set to @samp{Exp} when
|
||
it is created. The state is visible in the output from
|
||
@var{cvs log} (@pxref{log}), and in the
|
||
@samp{$@asis{}Log$} and @samp{$@asis{}State$} keywords
|
||
(@pxref{Keyword substitution}). Note that @sc{cvs}
|
||
uses the @code{dead} state for its own purposes; to
|
||
take a file to or from the @code{dead} state use
|
||
commands like @code{cvs remove} and @code{cvs add}, not
|
||
@code{cvs admin -s}.
|
||
|
||
@item -t[@var{file}]
|
||
Useful with @sc{cvs}. Write descriptive text from the
|
||
contents of the named @var{file} into the RCS file,
|
||
deleting the existing text. The @var{file} pathname
|
||
may not begin with @samp{-}. If @var{file} is omitted,
|
||
obtain the text from standard input, terminated by
|
||
end-of-file or by a line containing @samp{.} by itself.
|
||
Prompt for the text if interaction is possible; see
|
||
@samp{-I}. The descriptive text can be seen in the
|
||
output from @samp{cvs log} (@pxref{log}).
|
||
|
||
@item -t-@var{string}
|
||
Similar to @samp{-t@var{file}}. Write descriptive text
|
||
from the @var{string} into the @sc{rcs} file, deleting
|
||
the existing text.
|
||
|
||
@item -U
|
||
Set locking to non-strict. Non-strict locking means
|
||
that the owner of a file need not lock a revision for
|
||
checkin. For use with @sc{cvs}, strict locking must be
|
||
set; see the discussion under the @samp{-l} option
|
||
above.
|
||
|
||
@item -u[@var{rev}]
|
||
See the option @samp{-l} above, for a discussion of
|
||
using this option with @sc{cvs}. Unlock the revision
|
||
with number @var{rev}. If a branch is given, unlock
|
||
the latest revision on that branch. If @var{rev} is
|
||
omitted, remove the latest lock held by the caller.
|
||
Normally, only the locker of a revision may unlock it.
|
||
Somebody else unlocking a revision breaks the lock.
|
||
This causes a mail message to be sent to the original
|
||
locker. The message contains a commentary solicited
|
||
from the breaker. The commentary is terminated by
|
||
end-of-file or by a line containing @code{.} by itself.
|
||
|
||
@item -V@var{n}
|
||
Emulate @sc{rcs} version @var{n}. Use -V@var{n} to make
|
||
an @sc{rcs} file acceptable to @sc{rcs} version @var{n}
|
||
by discarding information that would confuse version
|
||
@var{n}.
|
||
|
||
@item -x@var{suffixes}
|
||
Useless with @sc{cvs}. Use @var{suffixes} to
|
||
characterize RCS files.
|
||
@end table
|
||
|
||
|
||
@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
|
||
@node admin examples
|
||
@appendixsubsec admin examples
|
||
|
||
@appendixsubsubsec Outdating is dangerous
|
||
|
||
First, an example of how @emph{not} to use the
|
||
@code{admin} command. It is included to stress the
|
||
fact that this command can be quite dangerous unless
|
||
you know @emph{exactly} what you are doing.
|
||
|
||
The @samp{-o} option can be used to @dfn{outdate} old revisions
|
||
from the history file. If you are short on disc this option
|
||
might help you. But think twice before using it---there is no
|
||
way short of restoring the latest backup to undo this command!
|
||
|
||
The next line is an example of a command that you would
|
||
@emph{not} like to execute.
|
||
|
||
@example
|
||
$ cvs admin -o:R_1_02 .
|
||
@end example
|
||
|
||
The above command will delete all revisions up to, and
|
||
including, the revision that corresponds to the tag
|
||
R_1_02. But beware! If there are files that have not
|
||
changed between R_1_02 and R_1_03 the file will have
|
||
@emph{the same} numerical revision number assigned to
|
||
the tags R_1_02 and R_1_03. So not only will it be
|
||
impossible to retrieve R_1_02; R_1_03 will also have to
|
||
be restored from the tapes!
|
||
|
||
@appendixsubsubsec Comment leaders
|
||
@cindex Comment leader
|
||
@cindex Log keyword, selecting comment leader
|
||
@cindex Nroff (selecting comment leader)
|
||
|
||
If you use the @code{$@asis{}Log$} keyword and you do
|
||
not agree with the guess for comment leader that
|
||
@sc{cvs} has done, you can enforce your will with
|
||
@code{cvs admin -c}. This might be suitable for
|
||
@code{nroff} source:
|
||
|
||
@example
|
||
$ cvs admin -c'.\" ' *.man
|
||
$ rm *.man
|
||
$ cvs update
|
||
@end example
|
||
|
||
The two last steps are to make sure that you get the
|
||
versions with correct comment leaders in your working
|
||
files.
|
||
|
||
@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
|
||
@node checkout
|
||
@appendixsec checkout---Check out sources for editing
|
||
@cindex Checkout (subcommand)
|
||
@cindex Co (subcommand)
|
||
|
||
@itemize @bullet
|
||
@item
|
||
Synopsis: checkout [options] modules@dots{}
|
||
@item
|
||
Requires: repository.
|
||
@item
|
||
Changes: working directory.
|
||
@item
|
||
Synonyms: co, get
|
||
@end itemize
|
||
|
||
Make a working directory containing copies of the
|
||
source files specified by @var{modules}. You must execute
|
||
@code{checkout} before using most of the other @sc{cvs}
|
||
commands, since most of them operate on your working
|
||
directory.
|
||
|
||
The @var{modules} part of the command are either
|
||
symbolic names for some
|
||
collection of source directories and files, or paths to
|
||
directories or files in the repository. The symbolic
|
||
names are defined in the @samp{modules} file.
|
||
@xref{modules}.
|
||
@c Needs an example, particularly of the non-"modules"
|
||
@c case but probably of both.
|
||
|
||
Depending on the modules you specify, @code{checkout} may
|
||
recursively create directories and populate them with
|
||
the appropriate source files. You can then edit these
|
||
source files at any time (regardless of whether other
|
||
software developers are editing their own copies of the
|
||
sources); update them to include new changes applied by
|
||
others to the source repository; or commit your work as
|
||
a permanent change to the source repository.
|
||
|
||
Note that @code{checkout} is used to create
|
||
directories. The top-level directory created is always
|
||
added to the directory where @code{checkout} is
|
||
invoked, and usually has the same name as the specified
|
||
module. In the case of a module alias, the created
|
||
sub-directory may have a different name, but you can be
|
||
sure that it will be a sub-directory, and that
|
||
@code{checkout} will show the relative path leading to
|
||
each file as it is extracted into your private work
|
||
area (unless you specify the @samp{-Q} global option).
|
||
|
||
The files created by @code{checkout} are created
|
||
read-write, unless the @samp{-r} option to @sc{cvs}
|
||
(@pxref{Global options}) is specified, the
|
||
@code{CVSREAD} environment variable is specified
|
||
(@pxref{Environment variables}), or a watch is in
|
||
effect for that file (@pxref{Watches}).
|
||
|
||
@c FIXME: misleading--checkout takes a module as
|
||
@c argument, and update does not--so -d behavior is not the only
|
||
@c difference.
|
||
Running @code{checkout} on a directory that was already
|
||
built by a prior @code{checkout} is also permitted, and
|
||
has the same effect as specifying the @samp{-d} option
|
||
to the @code{update} command, that is, any new
|
||
directories that have been created in the repository
|
||
will appear in your work area. @xref{update}.
|
||
|
||
For the output produced by the @code{checkout} command
|
||
see @ref{update output}.
|
||
|
||
@menu
|
||
* checkout options:: checkout options
|
||
* checkout examples:: checkout examples
|
||
@end menu
|
||
|
||
@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
|
||
@node checkout options
|
||
@appendixsubsec checkout options
|
||
|
||
These standard options are supported by @code{checkout}
|
||
(@pxref{Common options}, for a complete description of
|
||
them):
|
||
|
||
@table @code
|
||
@item -D @var{date}
|
||
Use the most recent revision no later than @var{date}.
|
||
This option is sticky, and implies @samp{-P}. See
|
||
@ref{Sticky tags}, for more information on sticky tags/dates.
|
||
|
||
@item -f
|
||
Only useful with the @samp{-D @var{date}} or @samp{-r
|
||
@var{tag}} flags. If no matching revision is found,
|
||
retrieve the most recent revision (instead of ignoring
|
||
the file).
|
||
|
||
@item -k @var{kflag}
|
||
Process @sc{rcs} keywords according to @var{kflag}. See
|
||
co(1). This option is sticky; future updates of
|
||
this file in this working directory will use the same
|
||
@var{kflag}. The @code{status} command can be viewed
|
||
to see the sticky options. See @ref{Invoking CVS}, for
|
||
more information on the @code{status} command.
|
||
|
||
@item -l
|
||
Local; run only in current working directory.
|
||
|
||
@item -n
|
||
Do not run any checkout program (as specified
|
||
with the @samp{-o} option in the modules file;
|
||
@pxref{modules}).
|
||
|
||
@item -P
|
||
Prune empty directories. See @ref{Moving directories}.
|
||
|
||
@item -p
|
||
Pipe files to the standard output.
|
||
|
||
@item -R
|
||
Checkout directories recursively. This option is on by default.
|
||
|
||
@item -r @var{tag}
|
||
Use revision @var{tag}. This option is sticky, and implies @samp{-P}.
|
||
See @ref{Sticky tags}, for more information on sticky tags/dates.
|
||
@end table
|
||
|
||
In addition to those, you can use these special command
|
||
options with @code{checkout}:
|
||
|
||
@table @code
|
||
@item -A
|
||
Reset any sticky tags, dates, or @samp{-k} options.
|
||
See @ref{Sticky tags}, for more information on sticky tags/dates.
|
||
|
||
@item -c
|
||
Copy the module file, sorted, to the standard output,
|
||
instead of creating or modifying any files or
|
||
directories in your working directory.
|
||
|
||
@c Should clarify whether dir can specify a
|
||
@c subdirectory (for example "foo/bar"). As of May,
|
||
@c 1996, it is said to work for local CVS if the parent
|
||
@c directories already exist, and not at all for remote
|
||
@c CVS. The remote CVS behavior at least seems like it
|
||
@c is clearly a bug.
|
||
@item -d @var{dir}
|
||
Create a directory called @var{dir} for the working
|
||
files, instead of using the module name. Unless you
|
||
also use @samp{-N}, the paths created under @var{dir}
|
||
will be as short as possible.
|
||
@c FIXME: What the #$@!#$# does "short as possible" mean?
|
||
|
||
@item -j @var{tag}
|
||
With two @samp{-j} options, merge changes from the
|
||
revision specified with the first @samp{-j} option to
|
||
the revision specified with the second @samp{j} option,
|
||
into the working directory.
|
||
|
||
With one @samp{-j} option, merge changes from the
|
||
ancestor revision to the revision specified with the
|
||
@samp{-j} option, into the working directory. The
|
||
ancestor revision is the common ancestor of the
|
||
revision which the working directory is based on, and
|
||
the revision specified in the @samp{-j} option.
|
||
|
||
In addition, each -j option can contain an optional
|
||
date specification which, when used with branches, can
|
||
limit the chosen revision to one within a specific
|
||
date. An optional date is specified by adding a colon
|
||
(:) to the tag:
|
||
@samp{-j@var{Symbolic_Tag}:@var{Date_Specifier}}.
|
||
|
||
@xref{Merging}.
|
||
|
||
@item -N
|
||
Only useful together with @samp{-d @var{dir}}. With this
|
||
option, @sc{cvs} will not shorten module paths in your
|
||
working directory. (Normally, @sc{cvs} shortens paths as
|
||
much as possible when you specify an explicit target
|
||
directory).
|
||
|
||
@item -s
|
||
Like @samp{-c}, but include the status of all modules,
|
||
and sort it by the status string. @xref{modules}, for
|
||
info about the @samp{-s} option that is used inside the
|
||
modules file to set the module status.
|
||
@end table
|
||
|
||
@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
|
||
@node checkout examples
|
||
@appendixsubsec checkout examples
|
||
|
||
Get a copy of the module @samp{tc}:
|
||
|
||
@example
|
||
$ cvs checkout tc
|
||
@end example
|
||
|
||
Get a copy of the module @samp{tc} as it looked one day
|
||
ago:
|
||
|
||
@example
|
||
$ cvs checkout -D yesterday tc
|
||
@end example
|
||
|
||
@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
|
||
@node commit
|
||
@appendixsec commit---Check files into the repository
|
||
@cindex Commit (subcommand)
|
||
|
||
@itemize @bullet
|
||
@item
|
||
Synopsis: commit [-lnRf] [-m 'log_message' |
|
||
-F file] [-r revision] [files@dots{}]
|
||
@item
|
||
Requires: working directory, repository.
|
||
@item
|
||
Changes: repository.
|
||
@item
|
||
Synonym: ci
|
||
@end itemize
|
||
|
||
Use @code{commit} when you want to incorporate changes
|
||
from your working source files into the source
|
||
repository.
|
||
|
||
If you don't specify particular files to commit, all of
|
||
the files in your working current directory are
|
||
examined. @code{commit} is careful to change in the
|
||
repository only those files that you have really
|
||
changed. By default (or if you explicitly specify the
|
||
@samp{-R} option), files in subdirectories are also
|
||
examined and committed if they have changed; you can
|
||
use the @samp{-l} option to limit @code{commit} to the
|
||
current directory only.
|
||
|
||
@code{commit} verifies that the selected files are up
|
||
to date with the current revisions in the source
|
||
repository; it will notify you, and exit without
|
||
committing, if any of the specified files must be made
|
||
current first with @code{update} (@pxref{update}).
|
||
@code{commit} does not call the @code{update} command
|
||
for you, but rather leaves that for you to do when the
|
||
time is right.
|
||
|
||
When all is well, an editor is invoked to allow you to
|
||
enter a log message that will be written to one or more
|
||
logging programs (@pxref{modules}, and @pxref{loginfo})
|
||
and placed in the @sc{rcs} history file inside the
|
||
repository. This log message can be retrieved with the
|
||
@code{log} command; @xref{log}. You can specify the
|
||
log message on the command line with the @samp{-m
|
||
@var{message}} option, and thus avoid the editor invocation,
|
||
or use the @samp{-F @var{file}} option to specify
|
||
that the argument file contains the log message.
|
||
|
||
@menu
|
||
* commit options:: commit options
|
||
* commit examples:: commit examples
|
||
@end menu
|
||
|
||
@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
|
||
@node commit options
|
||
@appendixsubsec commit options
|
||
|
||
These standard options are supported by @code{commit}
|
||
(@pxref{Common options}, for a complete description of
|
||
them):
|
||
|
||
@table @code
|
||
@item -l
|
||
Local; run only in current working directory.
|
||
|
||
@item -n
|
||
Do not run any module program.
|
||
|
||
@item -R
|
||
Commit directories recursively. This is on by default.
|
||
|
||
@item -r @var{revision}
|
||
Commit to @var{revision}. @var{revision} must be
|
||
either a branch, or a revision on the main trunk that
|
||
is higher than any existing revision number
|
||
(@pxref{Assigning revisions}). You
|
||
cannot commit to a specific revision on a branch.
|
||
@c FIXME: Need xref for branch case.
|
||
@end table
|
||
|
||
@code{commit} also supports these options:
|
||
|
||
@table @code
|
||
@item -F @var{file}
|
||
Read the log message from @var{file}, instead
|
||
of invoking an editor.
|
||
|
||
@item -f
|
||
Note that this is not the standard behavior of
|
||
the @samp{-f} option as defined in @xref{Common options}.
|
||
|
||
Force @sc{cvs} to commit a new revision even if you haven't
|
||
made any changes to the file. If the current revision
|
||
of @var{file} is 1.7, then the following two commands
|
||
are equivalent:
|
||
|
||
@example
|
||
$ cvs commit -f @var{file}
|
||
$ cvs commit -r 1.8 @var{file}
|
||
@end example
|
||
|
||
@c This is odd, but it's how CVS has worked for some
|
||
@c time.
|
||
The @samp{-f} option disables recursion (i.e., it
|
||
implies @samp{-l}). To force @sc{cvs} to commit a new
|
||
revision for all files in all subdirectories, you must
|
||
use @samp{-f -R}.
|
||
|
||
@item -m @var{message}
|
||
Use @var{message} as the log message, instead of
|
||
invoking an editor.
|
||
@end table
|
||
|
||
@need 2000
|
||
@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
|
||
@node commit examples
|
||
@appendixsubsec commit examples
|
||
|
||
@appendixsubsubsec Committing to a branch
|
||
|
||
You can commit to a branch revision (one that has an
|
||
even number of dots) with the @samp{-r} option. To
|
||
create a branch revision, use the @samp{-b} option
|
||
of the @code{rtag} or @code{tag} commands (@pxref{tag}
|
||
or @pxref{rtag}). Then, either @code{checkout} or
|
||
@code{update} can be used to base your sources on the
|
||
newly created branch. From that point on, all
|
||
@code{commit} changes made within these working sources
|
||
will be automatically added to a branch revision,
|
||
thereby not disturbing main-line development in any
|
||
way. For example, if you had to create a patch to the
|
||
1.2 version of the product, even though the 2.0 version
|
||
is already under development, you might do:
|
||
|
||
@example
|
||
$ cvs rtag -b -r FCS1_2 FCS1_2_Patch product_module
|
||
$ cvs checkout -r FCS1_2_Patch product_module
|
||
$ cd product_module
|
||
[[ hack away ]]
|
||
$ cvs commit
|
||
@end example
|
||
|
||
@noindent
|
||
This works automatically since the @samp{-r} option is
|
||
sticky.
|
||
|
||
@appendixsubsubsec Creating the branch after editing
|
||
|
||
Say you have been working on some extremely
|
||
experimental software, based on whatever revision you
|
||
happened to checkout last week. If others in your
|
||
group would like to work on this software with you, but
|
||
without disturbing main-line development, you could
|
||
commit your change to a new branch. Others can then
|
||
checkout your experimental stuff and utilize the full
|
||
benefit of @sc{cvs} conflict resolution. The scenario might
|
||
look like:
|
||
|
||
@c FIXME: Should we be recommending tagging the branchpoint?
|
||
@example
|
||
[[ hacked sources are present ]]
|
||
$ cvs tag -b EXPR1
|
||
$ cvs update -r EXPR1
|
||
$ cvs commit
|
||
@end example
|
||
|
||
The @code{update} command will make the @samp{-r
|
||
EXPR1} option sticky on all files. Note that your
|
||
changes to the files will never be removed by the
|
||
@code{update} command. The @code{commit} will
|
||
automatically commit to the correct branch, because the
|
||
@samp{-r} is sticky. You could also do like this:
|
||
|
||
@c FIXME: Should we be recommending tagging the branchpoint?
|
||
@example
|
||
[[ hacked sources are present ]]
|
||
$ cvs tag -b EXPR1
|
||
$ cvs commit -r EXPR1
|
||
@end example
|
||
|
||
@noindent
|
||
but then, only those files that were changed by you
|
||
will have the @samp{-r EXPR1} sticky flag. If you hack
|
||
away, and commit without specifying the @samp{-r EXPR1}
|
||
flag, some files may accidentally end up on the main
|
||
trunk.
|
||
|
||
To work with you on the experimental change, others
|
||
would simply do
|
||
|
||
@example
|
||
$ cvs checkout -r EXPR1 whatever_module
|
||
@end example
|
||
|
||
@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
|
||
@node diff
|
||
@appendixsec diff---Show differences between revisions
|
||
@cindex Diff (subcommand)
|
||
|
||
@itemize @bullet
|
||
@item
|
||
Synopsis: diff [-lR] [rcsdiff_options] [[-r rev1 | -D date1] [-r rev2 | -D date2]] [files@dots{}]
|
||
@item
|
||
Requires: working directory, repository.
|
||
@item
|
||
Changes: nothing.
|
||
@end itemize
|
||
|
||
The @code{diff} command is used to compare different
|
||
revisions of files. The default action is to compare
|
||
your working files with the revisions they were based
|
||
on, and report any differences that are found.
|
||
|
||
If any file names are given, only those files are
|
||
compared. If any directories are given, all files
|
||
under them will be compared.
|
||
|
||
The exit status for diff is different than for other
|
||
@sc{cvs} commands; for details @ref{Exit status}.
|
||
|
||
@menu
|
||
* diff options:: diff options
|
||
* diff examples:: diff examples
|
||
@end menu
|
||
|
||
@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
|
||
@node diff options
|
||
@appendixsubsec diff options
|
||
|
||
These standard options are supported by @code{diff}
|
||
(@pxref{Common options}, for a complete description of
|
||
them):
|
||
|
||
@table @code
|
||
@item -D @var{date}
|
||
Use the most recent revision no later than @var{date}.
|
||
See @samp{-r} for how this affects the comparison.
|
||
|
||
@item -k @var{kflag}
|
||
Process @sc{rcs} keywords according to @var{kflag}. See
|
||
co(1).
|
||
|
||
@item -l
|
||
Local; run only in current working directory.
|
||
|
||
@item -R
|
||
Examine directories recursively. This option is on by
|
||
default.
|
||
|
||
@item -r @var{tag}
|
||
Compare with revision @var{tag}. Zero, one or two
|
||
@samp{-r} options can be present. With no @samp{-r}
|
||
option, the working file will be compared with the
|
||
revision it was based on. With one @samp{-r}, that
|
||
revision will be compared to your current working file.
|
||
With two @samp{-r} options those two revisions will be
|
||
compared (and your working file will not affect the
|
||
outcome in any way).
|
||
|
||
One or both @samp{-r} options can be replaced by a
|
||
@samp{-D @var{date}} option, described above.
|
||
|
||
@item --ifdef=@var{arg}
|
||
Output in ifdef format. Consult the documentation of
|
||
your underlying diff program concerning the @samp{-D}
|
||
option to diff, for more information on this format.
|
||
@end table
|
||
|
||
@c FIXME? Probably should document -c here, and
|
||
@c perhaps arrange for CVS to support it via a diff library or
|
||
@c some such. Or perhaps figure that "all" diff
|
||
@c programs support -c? Ideas is to preserve the
|
||
@c ability to pass the buck to diff on all the hairy
|
||
@c stuff, while still providing at least one, and
|
||
@c perhaps several popular standard formats. But this
|
||
@c is all in the idea stage, and probably needs more
|
||
@c thought and refinement. -u might be similar, in
|
||
@c terms of being something that it might make sense to
|
||
@c document here.
|
||
@c FIXME: also should be a way to pass through
|
||
@c arbitrary options, so that the user can do
|
||
@c "--pass=-Z --pass=foo" or something even if CVS
|
||
@c doesn't know about the -Z option to diff.
|
||
@c Note on -N: The current CVS implementation does require that the
|
||
@c underlying diff supports -N so we can document it as
|
||
@c a pass-through even if the implementation details
|
||
@c are more complicated.
|
||
@c
|
||
@c FIXME? Reference to discussion of which diff CVS
|
||
@c uses (one in path, or....).
|
||
The following options are passed through to
|
||
@code{rcsdiff}, which in turn passes them to
|
||
@code{diff}. The exact meaning of the options depends
|
||
on which @code{diff} you are using. See the
|
||
documentation for your @code{diff} for details.
|
||
|
||
@code{-a} @code{-b} @code{-B} @code{-c} @w{@code{-C}
|
||
@var{nlines}} @code{-d} @code{-e} @code{-f} @code{-h}
|
||
@code{-H} @code{-i} @code{-n} @code{-N} @code{-p}
|
||
@code{-s} @code{-t} @code{-u} @code{-U} @var{nlines}
|
||
@w{@code{-F} @var{regexp}} @w{@code{-I} @var{regexp}}
|
||
@w{@code{-L} @var{label}} @code{-T} @w{@code{-V}
|
||
@var{arg}} @w{@code{-W} @var{columns}} @code{-w}
|
||
@code{-y} @code{-0} @code{-1} @code{-2} @code{-3}
|
||
@code{-4} @code{-5} @code{-6} @code{-7} @code{-8}
|
||
@code{-9} @code{--binary} @code{--brief}
|
||
@code{--changed-group-format=@var{arg}}
|
||
@code{--context[=@var{lines}]} @code{--ed}
|
||
@code{--expand-tabs} @code{--forward-ed}
|
||
@code{--horizon-lines=@var{arg}}
|
||
@code{--ignore-all-space} @code{--ignore-blank-lines}
|
||
@code{--ignore-case}
|
||
@code{--ignore-matching-lines=@var{regexp}}
|
||
@code{--ignore-space-change} @code{--initial-tab}
|
||
@code{--label=@var{label}} @code{--left-column}
|
||
@code{--minimal} @code{--new-file}
|
||
@code{--new-line-format=@var{arg}}
|
||
@code{--old-line-format=@var{arg}} @code{--paginate}
|
||
@code{--rcs} @code{--report-identical-files}
|
||
@code{--code-c-function} @code{--side-by-side}
|
||
@code{--show-function-line=@var{regexp}}
|
||
@code{--speed-large-files}
|
||
@code{--suppress-common-lines} @code{--text}
|
||
@code{--unchanged-group-format=@var{arg}}
|
||
@code{--unified[=@var{lines}]}
|
||
@code{--width=@var{columns}}
|
||
|
||
@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
|
||
@node diff examples
|
||
@appendixsubsec diff examples
|
||
|
||
The following line produces a Unidiff (@samp{-u} flag)
|
||
between revision 1.14 and 1.19 of
|
||
@file{backend.c}. Due to the @samp{-kk} flag no
|
||
keywords are substituted, so differences that only depend
|
||
on keyword substitution are ignored.
|
||
|
||
@example
|
||
$ cvs diff -kk -u -r 1.14 -r 1.19 backend.c
|
||
@end example
|
||
|
||
Suppose the experimental branch EXPR1 was based on a
|
||
set of files tagged RELEASE_1_0. To see what has
|
||
happened on that branch, the following can be used:
|
||
|
||
@example
|
||
$ cvs diff -r RELEASE_1_0 -r EXPR1
|
||
@end example
|
||
|
||
A command like this can be used to produce a context
|
||
diff between two releases:
|
||
|
||
@example
|
||
$ cvs diff -c -r RELEASE_1_0 -r RELEASE_1_1 > diffs
|
||
@end example
|
||
|
||
If you are maintaining ChangeLogs, a command like the following
|
||
just before you commit your changes may help you write
|
||
the ChangeLog entry. All local modifications that have
|
||
not yet been committed will be printed.
|
||
|
||
@example
|
||
$ cvs diff -u | less
|
||
@end example
|
||
|
||
@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
|
||
@node export
|
||
@appendixsec export---Export sources from CVS, similar to checkout
|
||
@cindex Export (subcommand)
|
||
|
||
@itemize @bullet
|
||
@item
|
||
Synopsis: export [-flNnR] [-r rev|-D date] [-k subst] [-d dir] module@dots{}
|
||
@item
|
||
Requires: repository.
|
||
@item
|
||
Changes: current directory.
|
||
@end itemize
|
||
|
||
This command is a variant of @code{checkout}; use it
|
||
when you want a copy of the source for module without
|
||
the @sc{cvs} administrative directories. For example, you
|
||
might use @code{export} to prepare source for shipment
|
||
off-site. This command requires that you specify a
|
||
date or tag (with @samp{-D} or @samp{-r}), so that you
|
||
can count on reproducing the source you ship to others.
|
||
|
||
One often would like to use @samp{-kv} with @code{cvs
|
||
export}. This causes any @sc{rcs} keywords to be
|
||
expanded such that an import done at some other site
|
||
will not lose the keyword revision information. But be
|
||
aware that doesn't handle an export containing binary
|
||
files correctly. Also be aware that after having used
|
||
@samp{-kv}, one can no longer use the @code{ident}
|
||
command (which is part of the @sc{rcs} suite---see
|
||
ident(1)) which looks for @sc{rcs} keyword strings. If
|
||
you want to be able to use @code{ident} you must not
|
||
use @samp{-kv}.
|
||
|
||
@menu
|
||
* export options:: export options
|
||
@end menu
|
||
|
||
@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
|
||
@node export options
|
||
@appendixsubsec export options
|
||
|
||
These standard options are supported by @code{export}
|
||
(@pxref{Common options}, for a complete description of
|
||
them):
|
||
|
||
@table @code
|
||
@item -D @var{date}
|
||
Use the most recent revision no later than @var{date}.
|
||
|
||
@item -f
|
||
If no matching revision is found, retrieve the most
|
||
recent revision (instead of ignoring the file).
|
||
|
||
@item -l
|
||
Local; run only in current working directory.
|
||
|
||
@item -n
|
||
Do not run any checkout program.
|
||
|
||
@item -R
|
||
Export directories recursively. This is on by default.
|
||
|
||
@item -r @var{tag}
|
||
Use revision @var{tag}.
|
||
@end table
|
||
|
||
In addition, these options (that are common to
|
||
@code{checkout} and @code{export}) are also supported:
|
||
|
||
@table @code
|
||
@item -d @var{dir}
|
||
Create a directory called @var{dir} for the working
|
||
files, instead of using the module name. Unless you
|
||
also use @samp{-N}, the paths created under @var{dir}
|
||
will be as short as possible.
|
||
|
||
@item -k @var{subst}
|
||
Set keyword expansion mode (@pxref{Substitution modes}).
|
||
|
||
@item -N
|
||
Only useful together with @samp{-d @var{dir}}. With this
|
||
option, @sc{cvs} will not shorten module paths in your
|
||
working directory. (Normally, @sc{cvs} shortens paths as
|
||
much as possible when you specify an explicit target
|
||
directory.)
|
||
@end table
|
||
|
||
@ignore
|
||
@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
|
||
@c @node export examples
|
||
@appendixsubsec export examples
|
||
|
||
Contributed examples are gratefully accepted.
|
||
@c -- Examples here!!
|
||
@end ignore
|
||
|
||
@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
|
||
@node history
|
||
@appendixsec history---Show status of files and users
|
||
@cindex History (subcommand)
|
||
|
||
@itemize @bullet
|
||
@item
|
||
Synopsis: history [-report] [-flags] [-options args] [files@dots{}]
|
||
@item
|
||
Requires: the file @file{$CVSROOT/CVSROOT/history}
|
||
@item
|
||
Changes: nothing.
|
||
@end itemize
|
||
|
||
@sc{cvs} can keep a history file that tracks each use of the
|
||
@code{checkout}, @code{commit}, @code{rtag},
|
||
@code{update}, and @code{release} commands. You can
|
||
use @code{history} to display this information in
|
||
various formats.
|
||
|
||
Logging must be enabled by creating the file
|
||
@file{$CVSROOT/CVSROOT/history}.
|
||
|
||
@strong{Warning:} @code{history} uses @samp{-f}, @samp{-l},
|
||
@samp{-n}, and @samp{-p} in ways that conflict with the
|
||
normal use inside @sc{cvs} (@pxref{Common options}).
|
||
|
||
@menu
|
||
* history options:: history options
|
||
@end menu
|
||
|
||
@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
|
||
@node history options
|
||
@appendixsubsec history options
|
||
|
||
Several options (shown above as @samp{-report}) control what
|
||
kind of report is generated:
|
||
|
||
@table @code
|
||
@item -c
|
||
Report on each time commit was used (i.e., each time
|
||
the repository was modified).
|
||
|
||
@item -e
|
||
Everything (all record types); equivalent to specifying
|
||
@samp{-xMACFROGWUT}.
|
||
|
||
@item -m @var{module}
|
||
Report on a particular module. (You can meaningfully
|
||
use @samp{-m} more than once on the command line.)
|
||
|
||
@item -o
|
||
Report on checked-out modules.
|
||
|
||
@item -T
|
||
Report on all tags.
|
||
|
||
@item -x @var{type}
|
||
Extract a particular set of record types @var{type} from the @sc{cvs}
|
||
history. The types are indicated by single letters,
|
||
which you may specify in combination.
|
||
|
||
Certain commands have a single record type:
|
||
|
||
@table @code
|
||
@item F
|
||
release
|
||
@item O
|
||
checkout
|
||
@item E
|
||
export
|
||
@item T
|
||
rtag
|
||
@end table
|
||
|
||
@noindent
|
||
One of four record types may result from an update:
|
||
|
||
@table @code
|
||
@item C
|
||
A merge was necessary but collisions were
|
||
detected (requiring manual merging).
|
||
@item G
|
||
A merge was necessary and it succeeded.
|
||
@item U
|
||
A working file was copied from the repository.
|
||
@item W
|
||
The working copy of a file was deleted during
|
||
update (because it was gone from the repository).
|
||
@end table
|
||
|
||
@noindent
|
||
One of three record types results from commit:
|
||
|
||
@table @code
|
||
@item A
|
||
A file was added for the first time.
|
||
@item M
|
||
A file was modified.
|
||
@item R
|
||
A file was removed.
|
||
@end table
|
||
@end table
|
||
|
||
The options shown as @samp{-flags} constrain or expand
|
||
the report without requiring option arguments:
|
||
|
||
@table @code
|
||
@item -a
|
||
Show data for all users (the default is to show data
|
||
only for the user executing @code{history}).
|
||
|
||
@item -l
|
||
Show last modification only.
|
||
|
||
@item -w
|
||
Show only the records for modifications done from the
|
||
same working directory where @code{history} is
|
||
executing.
|
||
@end table
|
||
|
||
The options shown as @samp{-options @var{args}} constrain the report
|
||
based on an argument:
|
||
|
||
@table @code
|
||
@item -b @var{str}
|
||
Show data back to a record containing the string
|
||
@var{str} in either the module name, the file name, or
|
||
the repository path.
|
||
|
||
@item -D @var{date}
|
||
Show data since @var{date}. This is slightly different
|
||
from the normal use of @samp{-D @var{date}}, which
|
||
selects the newest revision older than @var{date}.
|
||
|
||
@item -p @var{repository}
|
||
Show data for a particular source repository (you
|
||
can specify several @samp{-p} options on the same command
|
||
line).
|
||
|
||
@item -r @var{rev}
|
||
Show records referring to revisions since the revision
|
||
or tag named @var{rev} appears in individual @sc{rcs}
|
||
files. Each @sc{rcs} file is searched for the revision or
|
||
tag.
|
||
|
||
@item -t @var{tag}
|
||
Show records since tag @var{tag} was last added to the the
|
||
history file. This differs from the @samp{-r} flag
|
||
above in that it reads only the history file, not the
|
||
@sc{rcs} files, and is much faster.
|
||
|
||
@item -u @var{name}
|
||
Show records for user @var{name}.
|
||
@end table
|
||
|
||
@ignore
|
||
@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
|
||
@c @node history examples
|
||
@appendixsubsec history examples
|
||
|
||
Contributed examples will gratefully be accepted.
|
||
@c -- Examples here!
|
||
@end ignore
|
||
|
||
@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
|
||
@node import
|
||
@appendixsec import---Import sources into CVS, using vendor branches
|
||
@cindex Import (subcommand)
|
||
|
||
@c FIXME: This node is way too long for one which has subnodes.
|
||
|
||
@itemize @bullet
|
||
@item
|
||
Synopsis: import [-options] repository vendortag releasetag@dots{}
|
||
@item
|
||
Requires: Repository, source distribution directory.
|
||
@item
|
||
Changes: repository.
|
||
@end itemize
|
||
|
||
Use @code{import} to incorporate an entire source
|
||
distribution from an outside source (e.g., a source
|
||
vendor) into your source repository directory. You can
|
||
use this command both for initial creation of a
|
||
repository, and for wholesale updates to the module
|
||
from the outside source. @xref{Tracking sources}, for
|
||
a discussion on this subject.
|
||
|
||
The @var{repository} argument gives a directory name
|
||
(or a path to a directory) under the @sc{cvs} root directory
|
||
for repositories; if the directory did not exist,
|
||
import creates it.
|
||
|
||
When you use import for updates to source that has been
|
||
modified in your source repository (since a prior
|
||
import), it will notify you of any files that conflict
|
||
in the two branches of development; use @samp{checkout
|
||
-j} to reconcile the differences, as import instructs
|
||
you to do.
|
||
|
||
If @sc{cvs} decides a file should be ignored
|
||
(@pxref{cvsignore}), it does not import it and prints
|
||
@samp{I } followed by the filename (@pxref{import output}, for a
|
||
complete description of the output).
|
||
|
||
If the file @file{$CVSROOT/CVSROOT/cvswrappers} exists,
|
||
any file whose names match the specifications in that
|
||
file will be treated as packages and the appropriate
|
||
filtering will be performed on the file/directory
|
||
before being imported, @xref{Wrappers}.
|
||
|
||
The outside source is saved in a first-level @sc{rcs}
|
||
branch, by default 1.1.1. Updates are leaves of this
|
||
branch; for example, files from the first imported
|
||
collection of source will be revision 1.1.1.1, then
|
||
files from the first imported update will be revision
|
||
1.1.1.2, and so on.
|
||
|
||
At least three arguments are required.
|
||
@var{repository} is needed to identify the collection
|
||
of source. @var{vendortag} is a tag for the entire
|
||
branch (e.g., for 1.1.1). You must also specify at
|
||
least one @var{releasetag} to identify the files at
|
||
the leaves created each time you execute @code{import}.
|
||
|
||
@c I'm not completely sure this belongs here. But
|
||
@c we need to say it _somewhere_ reasonably obvious; it
|
||
@c is a common misconception among people first learning CVS
|
||
Note that @code{import} does @emph{not} change the
|
||
directory in which you invoke it. In particular, it
|
||
does not set up that directory as a @sc{cvs} working
|
||
directory; if you want to work with the sources import
|
||
them first and then check them out into a different
|
||
directory (@pxref{Getting the source}).
|
||
|
||
@menu
|
||
* import options:: import options
|
||
* import output:: import output
|
||
* import examples:: import examples
|
||
@end menu
|
||
|
||
@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
|
||
@node import options
|
||
@appendixsubsec import options
|
||
|
||
This standard option is supported by @code{import}
|
||
(@pxref{Common options}, for a complete description):
|
||
|
||
@table @code
|
||
@item -m @var{message}
|
||
Use @var{message} as log information, instead of
|
||
invoking an editor.
|
||
@end table
|
||
|
||
There are three additional special options.
|
||
|
||
@table @code
|
||
@item -b @var{branch}
|
||
Specify a first-level branch other than 1.1.1. Unless
|
||
the @samp{-b @var{branch}} flag is given, revisions will
|
||
@emph{always} be made to the branch 1.1.1---even if a
|
||
@var{vendortag} that matches another branch is given!
|
||
What happens in that case, is that the tag will be
|
||
reset to 1.1.1. Warning: This behavior might change
|
||
in the future.
|
||
|
||
@item -k @var{subst}
|
||
Indicate the RCS keyword expansion mode desired. This
|
||
setting will apply to all files created during the
|
||
import, but not to any files that previously existed in
|
||
the repository. See @ref{Substitution modes}, for a
|
||
list of valid @samp{-k} settings.
|
||
|
||
@item -I @var{name}
|
||
Specify file names that should be ignored during
|
||
import. You can use this option repeatedly. To avoid
|
||
ignoring any files at all (even those ignored by
|
||
default), specify `-I !'.
|
||
|
||
@var{name} can be a file name pattern of the same type
|
||
that you can specify in the @file{.cvsignore} file.
|
||
@xref{cvsignore}.
|
||
@c -- Is this really true?
|
||
|
||
@item -W @var{spec}
|
||
Specify file names that should be filtered during
|
||
import. You can use this option repeatedly.
|
||
|
||
@var{spec} can be a file name pattern of the same type
|
||
that you can specify in the @file{.cvswrappers}
|
||
file. @xref{Wrappers}.
|
||
@end table
|
||
|
||
@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
|
||
@node import output
|
||
@appendixsubsec import output
|
||
|
||
@code{import} keeps you informed of its progress by printing a line
|
||
for each file, preceded by one character indicating the status of the file:
|
||
|
||
@table @code
|
||
@item U @var{file}
|
||
The file already exists in the repository and has not been locally
|
||
modified; a new revision has been created (if necessary).
|
||
|
||
@item N @var{file}
|
||
The file is a new file which has been added to the repository.
|
||
|
||
@item C @var{file}
|
||
The file already exists in the repository but has been locally modified;
|
||
you will have to merge the changes.
|
||
|
||
@item I @var{file}
|
||
The file is being ignored (@pxref{cvsignore}).
|
||
|
||
@cindex symbolic link, importing
|
||
@cindex link, symbolic, importing
|
||
@c FIXME: also (somewhere else) probably
|
||
@c should be documenting what happens if you "cvs add"
|
||
@c a symbolic link. Also maybe what happens if
|
||
@c you manually create symbolic links within the
|
||
@c repository (? - not sure why we'd want to suggest
|
||
@c doing that).
|
||
@item L @var{file}
|
||
The file is a symbolic link; @code{cvs import} ignores symbolic links.
|
||
People periodically suggest that this behavior should
|
||
be changed, but if there is a consensus on what it
|
||
should be changed to, it doesn't seem to be apparent.
|
||
(Various options in the @file{modules} file can be used
|
||
to recreate symbolic links on checkout, update, etc.;
|
||
@pxref{modules}.)
|
||
@end table
|
||
|
||
@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
|
||
@node import examples
|
||
@appendixsubsec import examples
|
||
|
||
@xref{Tracking sources}, and @xref{From files}.
|
||
|
||
@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
|
||
@node log
|
||
@appendixsec log---Print out log information for files
|
||
@cindex Log (subcommand)
|
||
|
||
@itemize @bullet
|
||
@item
|
||
Synopsis: log [options] [files@dots{}]
|
||
@item
|
||
Requires: repository, working directory.
|
||
@item
|
||
Changes: nothing.
|
||
@end itemize
|
||
|
||
Display log information for files. @code{log} used to
|
||
call the @sc{rcs} utility @code{rlog}. Although this
|
||
is no longer true in the current sources, this history
|
||
determines the format of the output and the options,
|
||
which are not quite in the style of the other @sc{cvs}
|
||
commands.
|
||
|
||
@cindex timezone, in output
|
||
@cindex zone, time, in output
|
||
@c Kind of a funny place to document the timezone used
|
||
@c in output from commands other than @code{log}.
|
||
@c There is also more we need to say about this,
|
||
@c including what happens in a client/server environment.
|
||
The output includes the location of the @sc{rcs} file,
|
||
the @dfn{head} revision (the latest revision on the
|
||
trunk), all symbolic names (tags) and some other
|
||
things. For each revision, the revision number, the
|
||
author, the number of lines added/deleted and the log
|
||
message are printed. All times are displayed in
|
||
Coordinated Universal Time (UTC). (Other parts of
|
||
@sc{cvs} print times in the local timezone).
|
||
@c FIXCVS: need a better way to control the timezone
|
||
@c used in output. Previous/current versions of CVS did/do
|
||
@c sometimes support -z in RCSINIT, and/or an
|
||
@c undocumented (except by reference to 'rlog') -z option
|
||
@c to cvs log, but this has not been a consistent,
|
||
@c documented feature. Perhaps a new global option,
|
||
@c where LT means the client's timezone, which the
|
||
@c client then communicates to the server, is the
|
||
@c right solution.
|
||
|
||
@strong{Warning:} @code{log} uses @samp{-R} in a way that conflicts
|
||
with the normal use inside @sc{cvs} (@pxref{Common options}).
|
||
|
||
@menu
|
||
* log options:: log options
|
||
* log examples:: log examples
|
||
@end menu
|
||
|
||
@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
|
||
@node log options
|
||
@appendixsubsec log options
|
||
|
||
By default, @code{log} prints all information that is
|
||
available. All other options restrict the output.
|
||
|
||
@table @code
|
||
@item -b
|
||
Print information about the revisions on the default
|
||
branch, normally the highest branch on the trunk.
|
||
|
||
@item -d @var{dates}
|
||
Print information about revisions with a checkin
|
||
date/time in the range given by the
|
||
semicolon-separated list of dates. The date formats
|
||
accepted are those accepted by the @samp{-D} option to
|
||
many other @sc{cvs} commands (@pxref{Common options}).
|
||
Dates can be combined into ranges as follows:
|
||
|
||
@c Should we be thinking about accepting ISO8601
|
||
@c ranges? For example "1972-09-10/1972-09-12".
|
||
@table @code
|
||
@item @var{d1}<@var{d2}
|
||
@itemx @var{d2}>@var{d1}
|
||
Select the revisions that were deposited between
|
||
@var{d1} and @var{d2}.
|
||
|
||
@item <@var{d}
|
||
@itemx @var{d}>
|
||
Select all revisions dated @var{d} or earlier.
|
||
|
||
@item @var{d}<
|
||
@itemx >@var{d}
|
||
Select all revisions dated @var{d} or later.
|
||
|
||
@item @var{d}
|
||
Select the single, latest revision dated @var{d} or
|
||
earlier.
|
||
@end table
|
||
|
||
The @samp{>} or @samp{<} characters may be followed by
|
||
@samp{=} to indicate an inclusive range rather than an
|
||
exclusive one.
|
||
|
||
Note that the separator is a semicolon (;).
|
||
|
||
@item -h
|
||
Print only the @sc{rcs} pathname, working pathname, head,
|
||
default branch, access list, locks, symbolic names, and
|
||
suffix.
|
||
|
||
@item -l
|
||
Local; run only in current working directory. (Default
|
||
is to run recursively).
|
||
|
||
@item -N
|
||
Do not print the list of tags for this file. This
|
||
option can be very useful when your site uses a lot of
|
||
tags, so rather than "more"'ing over 3 pages of tag
|
||
information, the log information is presented without
|
||
tags at all.
|
||
|
||
@item -R
|
||
Print only the name of the @sc{rcs} history file.
|
||
|
||
@item -r@var{revisions}
|
||
Print information about revisions given in the
|
||
comma-separated list @var{revisions} of revisions and
|
||
ranges. The following table explains the available
|
||
range formats:
|
||
|
||
@table @code
|
||
@item @var{rev1}:@var{rev2}
|
||
Revisions @var{rev1} to @var{rev2} (which must be on
|
||
the same branch).
|
||
|
||
@item :@var{rev}
|
||
Revisions from the beginning of the branch up to
|
||
and including @var{rev}.
|
||
|
||
@item @var{rev}:
|
||
Revisions starting with @var{rev} to the end of the
|
||
branch containing @var{rev}.
|
||
|
||
@item @var{branch}
|
||
An argument that is a branch means all revisions on
|
||
that branch.
|
||
|
||
@item @var{branch1}:@var{branch2}
|
||
A range of branches means all revisions
|
||
on the branches in that range.
|
||
|
||
@item @var{branch}.
|
||
The latest revision in @var{branch}.
|
||
@end table
|
||
|
||
A bare @samp{-r} with no revisions means the latest
|
||
revision on the default branch, normally the trunk.
|
||
There can be no space between the @samp{-r} option and
|
||
its argument.
|
||
|
||
@item -s @var{states}
|
||
Print information about revisions whose state
|
||
attributes match one of the states given in the
|
||
comma-separated list @var{states}.
|
||
|
||
@item -t
|
||
Print the same as @samp{-h}, plus the descriptive text.
|
||
|
||
@item -w@var{logins}
|
||
Print information about revisions checked in by users
|
||
with login names appearing in the comma-separated list
|
||
@var{logins}. If @var{logins} is omitted, the user's
|
||
login is assumed. There can be no space between the
|
||
@samp{-w} option and its argument.
|
||
@end table
|
||
|
||
@code{log} prints the intersection of the revisions
|
||
selected with the options @samp{-d}, @samp{-s}, and
|
||
@samp{-w}, intersected with the union of the revisions
|
||
selected by @samp{-b} and @samp{-r}.
|
||
|
||
@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
|
||
@node log examples
|
||
@appendixsubsec log examples
|
||
|
||
Contributed examples are gratefully accepted.
|
||
|
||
@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
|
||
@node rdiff
|
||
@appendixsec rdiff---'patch' format diffs between releases
|
||
@cindex Rdiff (subcommand)
|
||
|
||
@itemize @bullet
|
||
@item
|
||
rdiff [-flags] [-V vn] [-r t|-D d [-r t2|-D d2]] modules@dots{}
|
||
@item
|
||
Requires: repository.
|
||
@item
|
||
Changes: nothing.
|
||
@item
|
||
Synonym: patch
|
||
@end itemize
|
||
|
||
Builds a Larry Wall format patch(1) file between two
|
||
releases, that can be fed directly into the patch
|
||
program to bring an old release up-to-date with the new
|
||
release. (This is one of the few @sc{cvs} commands that
|
||
operates directly from the repository, and doesn't
|
||
require a prior checkout.) The diff output is sent to
|
||
the standard output device.
|
||
|
||
You can specify (using the standard @samp{-r} and
|
||
@samp{-D} options) any combination of one or two
|
||
revisions or dates. If only one revision or date is
|
||
specified, the patch file reflects differences between
|
||
that revision or date and the current head revisions in
|
||
the @sc{rcs} file.
|
||
|
||
Note that if the software release affected is contained
|
||
in more than one directory, then it may be necessary to
|
||
specify the @samp{-p} option to the patch command when
|
||
patching the old sources, so that patch is able to find
|
||
the files that are located in other directories.
|
||
|
||
@menu
|
||
* rdiff options:: rdiff options
|
||
* rdiff examples:: rdiff examples
|
||
@end menu
|
||
|
||
@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
|
||
@node rdiff options
|
||
@appendixsubsec rdiff options
|
||
|
||
These standard options are supported by @code{rdiff}
|
||
(@pxref{Common options}, for a complete description of
|
||
them):
|
||
|
||
@table @code
|
||
@item -D @var{date}
|
||
Use the most recent revision no later than @var{date}.
|
||
|
||
@item -f
|
||
If no matching revision is found, retrieve the most
|
||
recent revision (instead of ignoring the file).
|
||
|
||
@item -l
|
||
Local; don't descend subdirectories.
|
||
|
||
@item -R
|
||
Examine directories recursively. This option is on by default.
|
||
|
||
@item -r @var{tag}
|
||
Use revision @var{tag}.
|
||
@end table
|
||
|
||
In addition to the above, these options are available:
|
||
|
||
@table @code
|
||
@item -c
|
||
Use the context diff format. This is the default format.
|
||
|
||
@item -s
|
||
Create a summary change report instead of a patch. The
|
||
summary includes information about files that were
|
||
changed or added between the releases. It is sent to
|
||
the standard output device. This is useful for finding
|
||
out, for example, which files have changed between two
|
||
dates or revisions.
|
||
|
||
@item -t
|
||
A diff of the top two revisions is sent to the standard
|
||
output device. This is most useful for seeing what the
|
||
last change to a file was.
|
||
|
||
@item -u
|
||
Use the unidiff format for the context diffs.
|
||
This option is not available if your diff does not
|
||
support the unidiff format. Remember that old versions
|
||
of the @code{patch} program can't handle the unidiff
|
||
format, so if you plan to post this patch to the net
|
||
you should probably not use @samp{-u}.
|
||
|
||
@item -V @var{vn}
|
||
Expand @sc{rcs} keywords according to the rules current in
|
||
@sc{rcs} version @var{vn} (the expansion format changed with
|
||
@sc{rcs} version 5).
|
||
@end table
|
||
|
||
@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
|
||
@node rdiff examples
|
||
@appendixsubsec rdiff examples
|
||
|
||
Suppose you receive mail from @t{foo@@bar.com} asking for an
|
||
update from release 1.2 to 1.4 of the tc compiler. You
|
||
have no such patches on hand, but with @sc{cvs} that can
|
||
easily be fixed with a command such as this:
|
||
|
||
@example
|
||
$ cvs rdiff -c -r FOO1_2 -r FOO1_4 tc | \
|
||
$$ Mail -s 'The patches you asked for' foo@@bar.com
|
||
@end example
|
||
|
||
Suppose you have made release 1.3, and forked a branch
|
||
called @samp{R_1_3fix} for bugfixes. @samp{R_1_3_1}
|
||
corresponds to release 1.3.1, which was made some time
|
||
ago. Now, you want to see how much development has been
|
||
done on the branch. This command can be used:
|
||
|
||
@example
|
||
$ cvs patch -s -r R_1_3_1 -r R_1_3fix module-name
|
||
cvs rdiff: Diffing module-name
|
||
File ChangeLog,v changed from revision 1.52.2.5 to 1.52.2.6
|
||
File foo.c,v changed from revision 1.52.2.3 to 1.52.2.4
|
||
File bar.h,v changed from revision 1.29.2.1 to 1.2
|
||
@end example
|
||
|
||
@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
|
||
@node release
|
||
@appendixsec release---Indicate that a Module is no longer in use
|
||
@cindex Release (subcommand)
|
||
|
||
@itemize @bullet
|
||
@item
|
||
release [-d] directories@dots{}
|
||
@item
|
||
Requires: Working directory.
|
||
@item
|
||
Changes: Working directory, history log.
|
||
@end itemize
|
||
|
||
This command is meant to safely cancel the effect of
|
||
@samp{cvs checkout}. Since @sc{cvs} doesn't lock files, it
|
||
isn't strictly necessary to use this command. You can
|
||
always simply delete your working directory, if you
|
||
like; but you risk losing changes you may have
|
||
forgotten, and you leave no trace in the @sc{cvs} history
|
||
file (@pxref{history file}) that you've abandoned your
|
||
checkout.
|
||
|
||
Use @samp{cvs release} to avoid these problems. This
|
||
command checks that no uncommitted changes are
|
||
present; that you are executing it from immediately
|
||
above a @sc{cvs} working directory; and that the repository
|
||
recorded for your files is the same as the repository
|
||
defined in the module database.
|
||
|
||
If all these conditions are true, @samp{cvs release}
|
||
leaves a record of its execution (attesting to your
|
||
intentionally abandoning your checkout) in the @sc{cvs}
|
||
history log.
|
||
|
||
@menu
|
||
* release options:: release options
|
||
* release output:: release output
|
||
* release examples:: release examples
|
||
@end menu
|
||
|
||
@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
|
||
@node release options
|
||
@appendixsubsec release options
|
||
|
||
The @code{release} command supports one command option:
|
||
|
||
@table @code
|
||
@item -d
|
||
Delete your working copy of the file if the release
|
||
succeeds. If this flag is not given your files will
|
||
remain in your working directory.
|
||
|
||
@strong{Warning:} The @code{release} command deletes
|
||
all directories and files recursively. This
|
||
has the very serious side-effect that any directory
|
||
that you have created inside your checked-out sources,
|
||
and not added to the repository (using the @code{add}
|
||
command; @pxref{Adding files}) will be silently deleted---even
|
||
if it is non-empty!
|
||
@end table
|
||
|
||
@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
|
||
@node release output
|
||
@appendixsubsec release output
|
||
|
||
Before @code{release} releases your sources it will
|
||
print a one-line message for any file that is not
|
||
up-to-date.
|
||
|
||
@strong{Warning:} Any new directories that you have
|
||
created, but not added to the @sc{cvs} directory hierarchy
|
||
with the @code{add} command (@pxref{Adding files}) will be
|
||
silently ignored (and deleted, if @samp{-d} is
|
||
specified), even if they contain files.
|
||
@c FIXCVS: This is a bug. But is it true? I think
|
||
@c maybe they print "? dir" now.
|
||
|
||
@table @code
|
||
@item U @var{file}
|
||
@itemx P @var{file}
|
||
There exists a newer revision of this file in the
|
||
repository, and you have not modified your local copy
|
||
of the file (@samp{U} and @samp{P} mean the same thing).
|
||
|
||
@item A @var{file}
|
||
The file has been added to your private copy of the
|
||
sources, but has not yet been committed to the
|
||
repository. If you delete your copy of the sources
|
||
this file will be lost.
|
||
|
||
@item R @var{file}
|
||
The file has been removed from your private copy of the
|
||
sources, but has not yet been removed from the
|
||
repository, since you have not yet committed the
|
||
removal. @xref{commit}.
|
||
|
||
@item M @var{file}
|
||
The file is modified in your working directory. There
|
||
might also be a newer revision inside the repository.
|
||
|
||
@item ? @var{file}
|
||
@var{file} is in your working directory, but does not
|
||
correspond to anything in the source repository, and is
|
||
not in the list of files for @sc{cvs} to ignore (see the
|
||
description of the @samp{-I} option, and
|
||
@pxref{cvsignore}). If you remove your working
|
||
sources, this file will be lost.
|
||
@end table
|
||
|
||
@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
|
||
@node release examples
|
||
@appendixsubsec release examples
|
||
|
||
Release the module, and delete your local working copy
|
||
of the files.
|
||
|
||
@example
|
||
$ cd .. # @r{You must stand immediately above the}
|
||
# @r{sources when you issue @samp{cvs release}.}
|
||
$ cvs release -d tc
|
||
You have [0] altered files in this repository.
|
||
Are you sure you want to release (and delete) module `tc': y
|
||
$
|
||
@end example
|
||
|
||
@node rtag
|
||
@appendixsec rtag---Add a symbolic tag to a module
|
||
@cindex Rtag (subcommand)
|
||
|
||
@itemize @bullet
|
||
@item
|
||
rtag [-falnR] [-b] [-d] [-r tag | -Ddate] symbolic_tag modules@dots{}
|
||
@item
|
||
Requires: repository.
|
||
@item
|
||
Changes: repository.
|
||
@item
|
||
Synonym: rfreeze
|
||
@end itemize
|
||
|
||
You can use this command to assign symbolic tags to
|
||
particular, explicitly specified source revisions in
|
||
the repository. @code{rtag} works directly on the
|
||
repository contents (and requires no prior checkout).
|
||
Use @code{tag} instead (@pxref{tag}), to base the
|
||
selection of revisions on the contents of your
|
||
working directory.
|
||
|
||
If you attempt to use a tag name that already exists,
|
||
@sc{cvs} will complain and not overwrite that tag. Use
|
||
the @samp{-F} option to force the new tag value.
|
||
|
||
@menu
|
||
* rtag options:: rtag options
|
||
@end menu
|
||
|
||
@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
|
||
@node rtag options
|
||
@appendixsubsec rtag options
|
||
|
||
These standard options are supported by @code{rtag}
|
||
(@pxref{Common options}, for a complete description of
|
||
them):
|
||
|
||
@table @code
|
||
@item -D @var{date}
|
||
Tag the most recent revision no later than @var{date}.
|
||
|
||
@item -f
|
||
Only useful with the @samp{-D @var{date}} or @samp{-r @var{tag}}
|
||
flags. If no matching revision is found, use the most
|
||
recent revision (instead of ignoring the file).
|
||
|
||
@item -F
|
||
Overwrite an existing tag of the same name on a
|
||
different revision.
|
||
@c FIXME: Needs an example, and/or more explanation.
|
||
@c Also needs to contrast this with the behavior if -F
|
||
@c is not specified, and the description needs to be
|
||
@c moved somewhere where it is shared between "tag" and
|
||
@c "rtag" (probably some sub-node of Revisions and
|
||
@c branches). Also should be clear about whether this
|
||
@c applies to branch tags, non-branch tags, or both.
|
||
@c Also this is *not* a common option.
|
||
|
||
@item -l
|
||
Local; run only in current working directory.
|
||
|
||
@item -n
|
||
Do not run any tag program that was specified with the
|
||
@samp{-t} flag inside the @file{modules} file.
|
||
(@pxref{modules}).
|
||
|
||
@item -R
|
||
Tag directories recursively. This is on by default.
|
||
|
||
@item -r @var{tag}
|
||
Only tag those files that contain @var{tag}. This can
|
||
be used to rename a tag: tag only the files identified
|
||
by the old tag, then delete the old tag, leaving the
|
||
new tag on exactly the same files as the old tag.
|
||
@end table
|
||
|
||
In addition to the above common options, these options
|
||
are available:
|
||
|
||
@table @code
|
||
@item -a
|
||
@c FIXME: What does this option mean in terms of user
|
||
@c concepts, not CVS internals?
|
||
Use the @samp{-a} option to have @code{rtag} look in the
|
||
@file{Attic} (@pxref{Attic}) for removed files
|
||
that contain the specified tag. The tag is removed from
|
||
these files, which makes it convenient to re-use a
|
||
symbolic tag as development continues (and files get
|
||
removed from the up-coming distribution).
|
||
|
||
@item -b
|
||
Make the tag a branch tag. @xref{Revisions and branches}.
|
||
|
||
@item -d
|
||
Delete the tag instead of creating it.
|
||
|
||
In general, tags (often the symbolic names of software
|
||
distributions) should not be removed, but the @samp{-d}
|
||
option is available as a means to remove completely
|
||
obsolete symbolic names if necessary (as might be the
|
||
case for an Alpha release, or if you mistagged a
|
||
module).
|
||
@end table
|
||
|
||
@ignore
|
||
@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
|
||
@c @node rtag examples
|
||
@appendixsubsec rtag examples
|
||
|
||
@c -- Examples here!
|
||
@end ignore
|
||
|
||
@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
|
||
@node tag
|
||
@appendixsec tag---Add a symbolic tag to checked out versions of files
|
||
@c -- //////// - unnecessary. Also
|
||
@c -- in a lot of other
|
||
@c -- places.
|
||
@cindex Tag (subcommand)
|
||
|
||
@itemize @bullet
|
||
@item
|
||
tag [-lR] [-b] [-c] [-d] symbolic_tag [files@dots{}]
|
||
@item
|
||
Requires: working directory, repository.
|
||
@item
|
||
Changes: repository.
|
||
@item
|
||
Synonym: freeze
|
||
@end itemize
|
||
|
||
Use this command to assign symbolic tags to the nearest
|
||
repository versions to your working sources. The tags
|
||
are applied immediately to the repository, as with
|
||
@code{rtag}, but the versions are supplied implicitly by the
|
||
@sc{cvs} records of your working files' history rather than
|
||
applied explicitly.
|
||
|
||
One use for tags is to record a snapshot of the
|
||
current sources when the software freeze date of a
|
||
project arrives. As bugs are fixed after the freeze
|
||
date, only those changed sources that are to be part of
|
||
the release need be re-tagged.
|
||
|
||
The symbolic tags are meant to permanently record which
|
||
revisions of which files were used in creating a
|
||
software distribution. The @code{checkout} and
|
||
@code{update} commands allow you to extract an exact
|
||
copy of a tagged release at any time in the future,
|
||
regardless of whether files have been changed, added,
|
||
or removed since the release was tagged.
|
||
|
||
This command can also be used to delete a symbolic tag,
|
||
or to create a branch. See the options section below.
|
||
|
||
If you attempt to use a tag name that already exists,
|
||
@sc{cvs} will complain and not overwrite that tag. Use
|
||
the @samp{-F} option to force the new tag value.
|
||
|
||
|
||
@menu
|
||
* tag options:: tag options
|
||
@end menu
|
||
|
||
@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
|
||
@node tag options
|
||
@appendixsubsec tag options
|
||
|
||
These standard options are supported by @code{tag}
|
||
(@pxref{Common options}, for a complete description of
|
||
them):
|
||
|
||
@table @code
|
||
@cindex renaming tags
|
||
@cindex tags, renaming
|
||
@cindex moving tags
|
||
@item -F
|
||
Overwrite an existing tag of the same name on a
|
||
different revision.
|
||
@c FIXME: See "rtag -F" for comments on this.
|
||
|
||
@item -l
|
||
Local; run only in current working directory.
|
||
|
||
@item -R
|
||
Tag directories recursively. This is on by default.
|
||
@end table
|
||
|
||
Two special options are available:
|
||
|
||
@table @code
|
||
@item -b
|
||
The -b option makes the tag a branch tag
|
||
(@pxref{Revisions and branches}), allowing concurrent, isolated
|
||
development. This is most useful for creating a patch
|
||
to a previously released software distribution.
|
||
|
||
@item -c
|
||
The -c option checks that all files which are to be tagged are
|
||
unmodified. This can be used to make sure that you can reconstruct the
|
||
current file contents.
|
||
|
||
@item -d
|
||
Delete a tag.
|
||
|
||
If you use @samp{cvs tag -d symbolic_tag}, the symbolic
|
||
tag you specify is deleted instead of being added.
|
||
Warning: Be very certain of your ground before you
|
||
delete a tag; doing this permanently discards some
|
||
historical information, which may later turn out to
|
||
be valuable.
|
||
@end table
|
||
|
||
@ignore
|
||
@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
|
||
@c @node tag examples
|
||
@appendixsubsec tag examples
|
||
|
||
@c -- FIXME
|
||
@end ignore
|
||
|
||
@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
|
||
@node update
|
||
@appendixsec update---Bring work tree in sync with repository
|
||
@cindex Update (subcommand)
|
||
|
||
@itemize @bullet
|
||
@item
|
||
update [-AdflPpR] [-d] [-r tag|-D date] files@dots{}
|
||
@item
|
||
Requires: repository, working directory.
|
||
@item
|
||
Changes: working directory.
|
||
@end itemize
|
||
|
||
After you've run checkout to create your private copy
|
||
of source from the common repository, other developers
|
||
will continue changing the central source. From time
|
||
to time, when it is convenient in your development
|
||
process, you can use the @code{update} command from
|
||
within your working directory to reconcile your work
|
||
with any revisions applied to the source repository
|
||
since your last checkout or update.
|
||
|
||
@menu
|
||
* update options:: update options
|
||
* update output:: update output
|
||
@end menu
|
||
|
||
@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
|
||
@node update options
|
||
@appendixsubsec update options
|
||
|
||
These standard options are available with @code{update}
|
||
(@pxref{Common options}, for a complete description of
|
||
them):
|
||
|
||
@table @code
|
||
@item -D date
|
||
Use the most recent revision no later than @var{date}.
|
||
This option is sticky, and implies @samp{-P}.
|
||
See @ref{Sticky tags}, for more information on sticky tags/dates.
|
||
|
||
@item -f
|
||
Only useful with the @samp{-D @var{date}} or @samp{-r
|
||
@var{tag}} flags. If no matching revision is found,
|
||
retrieve the most recent revision (instead of ignoring
|
||
the file).
|
||
|
||
@item -k @var{kflag}
|
||
Process @sc{rcs} keywords according to @var{kflag}. See
|
||
co(1). This option is sticky; future updates of
|
||
this file in this working directory will use the same
|
||
@var{kflag}. The @code{status} command can be viewed
|
||
to see the sticky options. See @ref{Invoking CVS}, for
|
||
more information on the @code{status} command.
|
||
|
||
@item -l
|
||
Local; run only in current working directory. @xref{Recursive behavior}.
|
||
|
||
@item -P
|
||
Prune empty directories. See @ref{Moving directories}.
|
||
|
||
@item -p
|
||
Pipe files to the standard output.
|
||
|
||
@item -R
|
||
Update directories recursively (default). @xref{Recursive
|
||
behavior}.
|
||
|
||
@item -r tag
|
||
Retrieve revision @var{tag}. This option is sticky,
|
||
and implies @samp{-P}.
|
||
See @ref{Sticky tags}, for more information on sticky tags/dates.
|
||
@end table
|
||
|
||
@need 800
|
||
These special options are also available with
|
||
@code{update}.
|
||
|
||
@table @code
|
||
@item -A
|
||
Reset any sticky tags, dates, or @samp{-k} options.
|
||
See @ref{Sticky tags}, for more information on sticky tags/dates.
|
||
|
||
@item -d
|
||
Create any directories that exist in the repository if
|
||
they're missing from the working directory. Normally,
|
||
@code{update} acts only on directories and files that
|
||
were already enrolled in your working directory.
|
||
|
||
This is useful for updating directories that were
|
||
created in the repository since the initial checkout;
|
||
but it has an unfortunate side effect. If you
|
||
deliberately avoided certain directories in the
|
||
repository when you created your working directory
|
||
(either through use of a module name or by listing
|
||
explicitly the files and directories you wanted on the
|
||
command line), then updating with @samp{-d} will create
|
||
those directories, which may not be what you want.
|
||
|
||
@item -I @var{name}
|
||
Ignore files whose names match @var{name} (in your
|
||
working directory) during the update. You can specify
|
||
@samp{-I} more than once on the command line to specify
|
||
several files to ignore. Use @samp{-I !} to avoid
|
||
ignoring any files at all. @xref{cvsignore}, for other
|
||
ways to make @sc{cvs} ignore some files.
|
||
|
||
@item -W@var{spec}
|
||
Specify file names that should be filtered during
|
||
update. You can use this option repeatedly.
|
||
|
||
@var{spec} can be a file name pattern of the same type
|
||
that you can specify in the @file{.cvswrappers}
|
||
file. @xref{Wrappers}.
|
||
|
||
@item -j@var{revision}
|
||
With two @samp{-j} options, merge changes from the
|
||
revision specified with the first @samp{-j} option to
|
||
the revision specified with the second @samp{j} option,
|
||
into the working directory.
|
||
|
||
With one @samp{-j} option, merge changes from the
|
||
ancestor revision to the revision specified with the
|
||
@samp{-j} option, into the working directory. The
|
||
ancestor revision is the common ancestor of the
|
||
revision which the working directory is based on, and
|
||
the revision specified in the @samp{-j} option.
|
||
|
||
In addition, each -j option can contain an optional
|
||
date specification which, when used with branches, can
|
||
limit the chosen revision to one within a specific
|
||
date. An optional date is specified by adding a colon
|
||
(:) to the tag:
|
||
@samp{-j@var{Symbolic_Tag}:@var{Date_Specifier}}.
|
||
|
||
@xref{Merging}.
|
||
|
||
@end table
|
||
|
||
@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
|
||
@node update output
|
||
@appendixsubsec update output
|
||
|
||
@code{update} and @code{checkout} keep you informed of
|
||
its progress by printing a line for each file, preceded
|
||
by one character indicating the status of the file:
|
||
|
||
@table @code
|
||
@item U @var{file}
|
||
The file was brought up to date with respect to the
|
||
repository. This is done for any file that exists in
|
||
the repository but not in your source, and for files
|
||
that you haven't changed but are not the most recent
|
||
versions available in the repository.
|
||
|
||
@item P @var{file}
|
||
Like @samp{U}, but the @sc{cvs} server sends a patch
|
||
instead of an entire file. These two things accomplish
|
||
the same thing.
|
||
|
||
@item A @var{file}
|
||
The file has been added to your private copy of the
|
||
sources, and will be added to the source repository
|
||
when you run @code{commit} on the file. This is a
|
||
reminder to you that the file needs to be committed.
|
||
|
||
@item R @var{file}
|
||
The file has been removed from your private copy of the
|
||
sources, and will be removed from the source repository
|
||
when you run @code{commit} on the file. This is a
|
||
reminder to you that the file needs to be committed.
|
||
|
||
@item M @var{file}
|
||
The file is modified in your working directory.
|
||
|
||
@samp{M} can indicate one of two states for a file
|
||
you're working on: either there were no modifications
|
||
to the same file in the repository, so that your file
|
||
remains as you last saw it; or there were modifications
|
||
in the repository as well as in your copy, but they
|
||
were merged successfully, without conflict, in your
|
||
working directory.
|
||
|
||
@sc{cvs} will print some messages if it merges your work,
|
||
and a backup copy of your working file (as it looked
|
||
before you ran @code{update}) will be made. The exact
|
||
name of that file is printed while @code{update} runs.
|
||
|
||
@item C @var{file}
|
||
@cindex .# files
|
||
@cindex __ files (VMS)
|
||
A conflict was detected while trying to merge your
|
||
changes to @var{file} with changes from the source
|
||
repository. @var{file} (the copy in your working
|
||
directory) is now the output of the rcsmerge(1) command
|
||
on the two revisions; an unmodified copy of your file
|
||
is also in your working directory, with the name
|
||
@file{.#@var{file}.@var{revision}} where @var{revision}
|
||
is the @sc{rcs} revision that your modified file started
|
||
from. Resolve the conflict as described in
|
||
@ref{Conflicts example}
|
||
@c "some systems" as in out-of-the-box OSes? Not as
|
||
@c far as I know. We need to advise sysadmins as well
|
||
@c as users how to set up this kind of purge, if that is
|
||
@c what they want.
|
||
@c We also might want to think about cleaner solutions,
|
||
@c like having CVS remove the .# file once the conflict
|
||
@c has been resolved or something like that.
|
||
(Note that some systems automatically purge
|
||
files that begin with @file{.#} if they have not been
|
||
accessed for a few days. If you intend to keep a copy
|
||
of your original file, it is a very good idea to rename
|
||
it.) Under @sc{vms}, the file name starts with
|
||
@file{__} rather than @file{.#}.
|
||
|
||
@item ? @var{file}
|
||
@var{file} is in your working directory, but does not
|
||
correspond to anything in the source repository, and is
|
||
not in the list of files for @sc{cvs} to ignore (see the
|
||
description of the @samp{-I} option, and
|
||
@pxref{cvsignore}).
|
||
@end table
|
||
|
||
@node Invoking CVS
|
||
@appendix Quick reference to CVS commands
|
||
@cindex Command reference
|
||
@cindex Reference, commands
|
||
@cindex Invoking CVS
|
||
|
||
This appendix describes how to invoke @sc{cvs}, with
|
||
references to where each command or feature is
|
||
described in detail. Other relevant references are the
|
||
@samp{--help}/@samp{-H} option to @sc{cvs}
|
||
(@pxref{Global options}) and @ref{Index}.
|
||
|
||
@c The idea behind this table is that we want each item
|
||
@c to be a sentence or two at most. Preferably a
|
||
@c single line.
|
||
@c
|
||
@c In some cases refs to "foo options" are just to get
|
||
@c this thing written quickly, not because the "foo
|
||
@c options" node is really the best place to point.
|
||
@table @code
|
||
@item add [@var{options}] [@var{files}@dots{}]
|
||
Add a new file/directory. See @ref{Adding files}.
|
||
|
||
@table @code
|
||
@item -k @var{kflag}
|
||
Set keyword expansion.
|
||
|
||
@item -m @var{msg}
|
||
Set file description.
|
||
@end table
|
||
|
||
@item admin [@var{options}] [@var{files}@dots{}]
|
||
Administration of history files in the repository. See
|
||
@ref{admin}.
|
||
@c This list omits those options which are not
|
||
@c documented as being useful with CVS. That might be
|
||
@c a mistake...
|
||
|
||
@table @code
|
||
@item -b[@var{rev}]
|
||
Set default branch.
|
||
@c FIXME: Should xref to a section which describes how
|
||
@c to use this with the vendor branch.
|
||
|
||
@item -c@var{string}
|
||
Set comment leader.
|
||
|
||
@item -k@var{subst}
|
||
Set keyword substitution. See @ref{Keyword
|
||
substitution}.
|
||
|
||
@item -l[@var{rev}]
|
||
Lock revision @var{rev}, or latest revision.
|
||
|
||
@item -m@var{rev}:@var{msg}
|
||
Replace the log message of revision @var{rev} with
|
||
@var{msg}.
|
||
|
||
@item -o@var{range}
|
||
Delete revisions from the history files
|
||
|
||
@item -q
|
||
Run quietly; do not print diagnostics.
|
||
|
||
@item -s@var{state}[:@var{rev}]
|
||
Set the state.
|
||
|
||
@c Does not work for client/server CVS
|
||
@item -t
|
||
Set file description from standard input.
|
||
|
||
@item -t@var{file}
|
||
Set file description from @var{file}.
|
||
|
||
@item -t-@var{string}
|
||
Set file description to @var{string}.
|
||
|
||
@item -u[@var{rev}]
|
||
Unlock revision @var{rev}, or latest revision.
|
||
@end table
|
||
|
||
@item annotate [@var{options}] [@var{files}@dots{}]
|
||
Show last revision where each line was modified. See
|
||
@ref{annotate}.
|
||
|
||
@table @code
|
||
@item -D @var{date}
|
||
Annotate the most recent revision no later than
|
||
@var{date}. See @ref{Common options}.
|
||
|
||
@item -f
|
||
Use head revision if tag/date not found. See
|
||
@ref{Common options}.
|
||
|
||
@item -l
|
||
Local; run only in current working directory. @xref{Recursive behavior}.
|
||
|
||
@item -R
|
||
Operate recursively (default). @xref{Recursive
|
||
behavior}.
|
||
|
||
@item -r @var{tag}
|
||
Annotate revision @var{tag}. See @ref{Common options}.
|
||
@end table
|
||
|
||
@item checkout [@var{options}] @var{modules}@dots{}
|
||
Get a copy of the sources. See @ref{checkout}.
|
||
|
||
@table @code
|
||
@item -A
|
||
Reset any sticky tags/date/options. See @ref{Sticky
|
||
tags} and @ref{Keyword substitution}.
|
||
|
||
@item -c
|
||
Output the module database. See @ref{checkout options}.
|
||
|
||
@item -D @var{date}
|
||
Check out revisions as of @var{date} (is sticky). See
|
||
@ref{Common options}.
|
||
|
||
@item -d @var{dir}
|
||
Check out into @var{dir}. See @ref{checkout options}.
|
||
|
||
@item -f
|
||
Use head revision if tag/date not found. See
|
||
@ref{Common options}.
|
||
|
||
@c Probably want to use rev1/rev2 style like for diff
|
||
@c -r. Here and in on-line help.
|
||
@item -j @var{rev}
|
||
Merge in changes. See @ref{checkout options}.
|
||
|
||
@item -k @var{kflag}
|
||
Use @var{kflag} keyword expansion. See
|
||
@ref{Substitution modes}.
|
||
|
||
@item -l
|
||
Local; run only in current working directory. @xref{Recursive behavior}.
|
||
|
||
@item -N
|
||
Don't shorten module paths if -d specified. See @ref{checkout options}.
|
||
|
||
@item -n
|
||
Do not run module program (if any). See @ref{checkout options}.
|
||
|
||
@item -P
|
||
Prune empty directories. See @ref{Moving directories}.
|
||
|
||
@item -p
|
||
Check out files to standard output (avoids
|
||
stickiness). See @ref{checkout options}.
|
||
|
||
@item -R
|
||
Operate recursively (default). @xref{Recursive
|
||
behavior}.
|
||
|
||
@item -r @var{tag}
|
||
Checkout revision @var{tag} (is sticky). See @ref{Common options}.
|
||
|
||
@item -s
|
||
Like -c, but include module status. See @ref{checkout options}.
|
||
@end table
|
||
|
||
@item commit [@var{options}] [@var{files}@dots{}]
|
||
Check changes into the repository. See @ref{commit}.
|
||
|
||
@table @code
|
||
@item -F @var{file}
|
||
Read log message from @var{file}. See @ref{commit options}.
|
||
|
||
@item -f
|
||
@c What is this "disables recursion"? It is from the
|
||
@c on-line help; is it documented in this manual?
|
||
Force the file to be committed; disables recursion.
|
||
See @ref{commit options}.
|
||
|
||
@item -l
|
||
Local; run only in current working directory. See @ref{Recursive behavior}.
|
||
|
||
@item -m @var{msg}
|
||
Use @var{msg} as log message. See @ref{commit options}.
|
||
|
||
@item -n
|
||
Do not run module program (if any). See @ref{commit options}.
|
||
|
||
@item -R
|
||
Operate recursively (default). @xref{Recursive
|
||
behavior}.
|
||
|
||
@item -r @var{rev}
|
||
Commit to @var{rev}. See @ref{commit options}.
|
||
@c FIXME: should be dragging over text from
|
||
@c commit options, especially if it can be cleaned up
|
||
@c and made concise enough.
|
||
@end table
|
||
|
||
@item diff [@var{options}] [@var{files}@dots{}]
|
||
Show differences between revisions. See @ref{diff}.
|
||
In addition to the options shown below, accepts a wide
|
||
variety of options to control output style, for example
|
||
@samp{-c} for context diffs.
|
||
|
||
@table @code
|
||
@item -D @var{date1}
|
||
Diff revision for date against working file. See
|
||
@ref{diff options}.
|
||
|
||
@item -D @var{date2}
|
||
Diff @var{rev1}/@var{date1} against @var{date2}. See
|
||
@ref{diff options}.
|
||
|
||
@item -l
|
||
Local; run only in current working directory. See @ref{Recursive behavior}.
|
||
|
||
@item -N
|
||
Include diffs for added and removed files. See
|
||
@ref{diff options}.
|
||
|
||
@item -R
|
||
Operate recursively (default). @xref{Recursive
|
||
behavior}.
|
||
|
||
@item -r @var{rev1}
|
||
Diff revision for @var{rev1} against working file. See
|
||
@ref{diff options}.
|
||
|
||
@item -r @var{rev2}
|
||
Diff rev1/date1 against rev2. See @ref{diff options}.
|
||
@end table
|
||
|
||
@item edit [@var{options}] [@var{files}@dots{}]
|
||
Get ready to edit a watched file. See @ref{Editing files}.
|
||
|
||
@table @code
|
||
@item -a @var{actions}
|
||
Specify actions for temporary watch, where
|
||
@var{actions} is @code{edit}, @code{unedit},
|
||
@code{commit}, @code{all}, or @code{none}. See
|
||
@ref{Editing files}.
|
||
|
||
@item -l
|
||
Local; run only in current working directory. See @ref{Recursive behavior}.
|
||
|
||
@item -R
|
||
Operate recursively (default). @xref{Recursive
|
||
behavior}.
|
||
@end table
|
||
|
||
@item editors [@var{options}] [@var{files}@dots{}]
|
||
See who is editing a watched file. See @ref{Watch information}.
|
||
|
||
@table @code
|
||
@item -l
|
||
Local; run only in current working directory. See @ref{Recursive behavior}.
|
||
|
||
@item -R
|
||
Operate recursively (default). @xref{Recursive
|
||
behavior}.
|
||
@end table
|
||
|
||
@item export [@var{options}] @var{modules}@dots{}
|
||
Export files from CVS. See @ref{export}.
|
||
|
||
@table @code
|
||
@item -D @var{date}
|
||
Check out revisions as of @var{date}. See
|
||
@ref{Common options}.
|
||
|
||
@item -d @var{dir}
|
||
Check out into @var{dir}. See @ref{export options}.
|
||
|
||
@item -f
|
||
Use head revision if tag/date not found. See
|
||
@ref{Common options}.
|
||
|
||
@item -k @var{kflag}
|
||
Use @var{kflag} keyword expansion. See
|
||
@ref{Substitution modes}.
|
||
|
||
@item -l
|
||
Local; run only in current working directory. @xref{Recursive behavior}.
|
||
|
||
@item -N
|
||
Don't shorten module paths if -d specified. See @ref{export options}.
|
||
|
||
@item -n
|
||
Do not run module program (if any). See @ref{export options}.
|
||
|
||
@item -P
|
||
Prune empty directories. See @ref{Moving directories}.
|
||
|
||
@item -R
|
||
Operate recursively (default). @xref{Recursive
|
||
behavior}.
|
||
|
||
@item -r @var{tag}
|
||
Checkout revision @var{tag} (is sticky). See @ref{Common options}.
|
||
@end table
|
||
|
||
@item history [@var{options}] [@var{files}@dots{}]
|
||
Show repository access history. See @ref{history}.
|
||
|
||
@table @code
|
||
@item -a
|
||
All users (default is self). See @ref{history options}.
|
||
|
||
@item -b @var{str}
|
||
Back to record with @var{str} in module/file/repos
|
||
field. See @ref{history options}.
|
||
|
||
@item -c
|
||
Report on committed (modified) files. See @ref{history options}.
|
||
|
||
@item -D @var{date}
|
||
Since @var{date}. See @ref{history options}.
|
||
|
||
@item -e
|
||
Report on all record types. See @ref{history options}.
|
||
|
||
@item -l
|
||
Last modified (committed or modified report). See @ref{history options}.
|
||
|
||
@item -m @var{module}
|
||
Report on @var{module} (repeatable). See @ref{history
|
||
options}.
|
||
|
||
@item -n @var{module}
|
||
In @var{module}. See @ref{history options}.
|
||
|
||
@item -o
|
||
Report on checked out modules. See @ref{history options}.
|
||
|
||
@item -r @var{rev}
|
||
Since revision @var{rev}. See @ref{history options}.
|
||
|
||
@item -T
|
||
@c What the @#$@# is a TAG? Same as a tag? This
|
||
@c wording is also in the online-line help.
|
||
Produce report on all TAGs. See @ref{history options}.
|
||
|
||
@item -t @var{tag}
|
||
Since tag record placed in history file (by anyone).
|
||
See @ref{history options}.
|
||
|
||
@item -u @var{user}
|
||
For user @var{user} (repeatable). See @ref{history
|
||
options}.
|
||
|
||
@item -w
|
||
Working directory must match. See @ref{history options}.
|
||
|
||
@item -x @var{types}
|
||
Report on @var{types}, one or more of
|
||
@code{TOEFWUCGMAR}. See @ref{history options}.
|
||
|
||
@item -z @var{zone}
|
||
Output for time zone @var{zone}. See @ref{history
|
||
options}.
|
||
@end table
|
||
|
||
@item import [@var{options}] @var{repository} @var{vendor-tag} @var{release-tags}@dots{}
|
||
Import files into CVS, using vendor branches. See
|
||
@ref{import}.
|
||
|
||
@table @code
|
||
@item -b @var{bra}
|
||
Import to vendor branch @var{bra}. See
|
||
@ref{import options}.
|
||
|
||
@item -d
|
||
Use the file's modification time as the time of
|
||
import. See @ref{import options}.
|
||
|
||
@item -k @var{kflag}
|
||
Set default RCS keyword substitution mode. See
|
||
@ref{import options}.
|
||
|
||
@item -m @var{msg}
|
||
Use @var{msg} for log message. See
|
||
@ref{import options}.
|
||
|
||
@item -I @var{ign}
|
||
More files to ignore (! to reset). See
|
||
@ref{import options}.
|
||
|
||
@item -W @var{spec}
|
||
More wrappers. See @ref{import options}.
|
||
@end table
|
||
|
||
@item init
|
||
Create a CVS repository if it doesn't exist. See
|
||
@ref{Creating a repository}.
|
||
|
||
@item log [@var{options}] [@var{files}@dots{}]
|
||
Print out history information for files. See @ref{log}.
|
||
|
||
@table @code
|
||
@item -b
|
||
Only list revisions on the default branch. See @ref{log options}.
|
||
|
||
@item -d @var{dates}
|
||
Specify dates (@var{d1}<@var{d2} for range, @var{d} for
|
||
latest before). See @ref{log options}.
|
||
|
||
@item -h
|
||
Only print header. See @ref{log options}.
|
||
|
||
@item -l
|
||
Local; run only in current working directory. See @ref{Recursive behavior}.
|
||
|
||
@item -N
|
||
Do not list tags. See @ref{log options}.
|
||
|
||
@item -R
|
||
Only print name of RCS file. See @ref{log options}.
|
||
|
||
@item -r @var{revs}
|
||
Only list revisions @var{revs}. See @ref{log options}.
|
||
|
||
@item -s @var{states}
|
||
Only list revisions with specified states. See @ref{log options}.
|
||
|
||
@item -t
|
||
Only print header and descriptive text. See @ref{log
|
||
options}.
|
||
|
||
@item -w @var{logins}
|
||
Only list revisions checked in by specified logins. See @ref{log options}.
|
||
@end table
|
||
|
||
@item login
|
||
Prompt for password for authenticating server. See
|
||
@ref{Password authentication client}.
|
||
|
||
@item logout
|
||
Remove stored password for authenticating server. See
|
||
@ref{Password authentication client}.
|
||
|
||
@item rdiff [@var{options}] @var{modules}@dots{}
|
||
Show differences between releases. See @ref{rdiff}.
|
||
|
||
@table @code
|
||
@item -c
|
||
Context diff output format (default). See @ref{rdiff options}.
|
||
|
||
@item -D @var{date}
|
||
Select revisions based on @var{date}. See @ref{Common options}.
|
||
|
||
@item -f
|
||
Use head revision if tag/date not found. See
|
||
@ref{Common options}.
|
||
|
||
@item -l
|
||
Local; run only in current working directory. See @ref{Recursive behavior}.
|
||
|
||
@item -R
|
||
Operate recursively (default). @xref{Recursive
|
||
behavior}.
|
||
|
||
@item -r @var{rev}
|
||
Select revisions based on @var{rev}. See @ref{Common options}.
|
||
|
||
@item -s
|
||
Short patch - one liner per file. See @ref{rdiff options}.
|
||
|
||
@item -t
|
||
Top two diffs - last change made to the file. See
|
||
@ref{diff options}.
|
||
|
||
@item -u
|
||
Unidiff output format. See @ref{rdiff options}.
|
||
|
||
@item -V @var{vers}
|
||
Use RCS Version @var{vers} for keyword expansion. See
|
||
@ref{rdiff options}.
|
||
@end table
|
||
|
||
@item release [@var{options}] @var{directory}
|
||
Indicate that a directory is no longer in use. See
|
||
@ref{release}.
|
||
|
||
@table @code
|
||
@item -d
|
||
Delete the given directory. See @ref{release options}.
|
||
@end table
|
||
|
||
@item remove [@var{options}] [@var{files}@dots{}]
|
||
Remove an entry from the repository. See @ref{Removing files}.
|
||
|
||
@table @code
|
||
@item -f
|
||
Delete the file before removing it. See @ref{Removing files}.
|
||
|
||
@item -l
|
||
Local; run only in current working directory. See @ref{Recursive behavior}.
|
||
|
||
@item -R
|
||
Operate recursively (default). @xref{Recursive
|
||
behavior}.
|
||
@end table
|
||
|
||
@item rtag [@var{options}] @var{tag} @var{modules}@dots{}
|
||
Add a symbolic tag to a module. See @ref{rtag}.
|
||
|
||
@table @code
|
||
@c Is this one of those dumb options which used to
|
||
@c work around the lack of death support?
|
||
@item -a
|
||
Clear tag from removed files that would not otherwise
|
||
be tagged. See @ref{rtag options}.
|
||
|
||
@item -b
|
||
Create a branch named @var{tag}. See @ref{rtag options}.
|
||
|
||
@item -D @var{date}
|
||
Tag revisions as of @var{date}. See @ref{rtag options}.
|
||
|
||
@item -d
|
||
Delete the given tag. See @ref{rtag options}.
|
||
|
||
@item -F
|
||
Move tag if it already exists. See @ref{rtag options}.
|
||
|
||
@item -f
|
||
Force a head revision match if tag/date not found.
|
||
See @ref{rtag options}.
|
||
|
||
@item -l
|
||
Local; run only in current working directory. See @ref{Recursive behavior}.
|
||
|
||
@item -n
|
||
No execution of tag program. See @ref{rtag options}.
|
||
|
||
@item -R
|
||
Operate recursively (default). @xref{Recursive
|
||
behavior}.
|
||
|
||
@item -r @var{tag}
|
||
Tag existing tag @var{tag}. See @ref{rtag options}.
|
||
@end table
|
||
|
||
@item status [@var{options}] @var{files}@dots{}
|
||
Display status information in a working directory. See
|
||
@ref{File status}.
|
||
|
||
@table @code
|
||
@item -l
|
||
Local; run only in current working directory. See @ref{Recursive behavior}.
|
||
|
||
@item -R
|
||
Operate recursively (default). @xref{Recursive
|
||
behavior}.
|
||
|
||
@item -v
|
||
Include tag information for file. See @ref{Tags}.
|
||
@end table
|
||
|
||
@item tag [@var{options}] @var{tag} [@var{files}@dots{}]
|
||
Add a symbolic tag to checked out version of files.
|
||
See @ref{tag}.
|
||
|
||
@table @code
|
||
@item -b
|
||
Create a branch named @var{tag}. See @ref{tag options}.
|
||
|
||
@item -D @var{date}
|
||
Tag revisions as of @var{date}. See @ref{tag options}.
|
||
|
||
@item -d
|
||
Delete the given tag. See @ref{tag options}.
|
||
|
||
@item -F
|
||
Move tag if it already exists. See @ref{tag options}.
|
||
|
||
@item -f
|
||
Force a head revision match if tag/date not found.
|
||
See @ref{tag options}.
|
||
|
||
@item -l
|
||
Local; run only in current working directory. See @ref{Recursive behavior}.
|
||
|
||
@item -n
|
||
No execution of tag program. See @ref{tag options}.
|
||
|
||
@item -R
|
||
Operate recursively (default). @xref{Recursive
|
||
behavior}.
|
||
|
||
@item -r @var{tag}
|
||
Tag existing tag @var{tag}. See @ref{tag options}.
|
||
@end table
|
||
|
||
@item unedit [@var{options}] [@var{files}@dots{}]
|
||
Undo an edit command. See @ref{Editing files}.
|
||
|
||
@table @code
|
||
@item -a @var{actions}
|
||
Specify actions for temporary watch, where
|
||
@var{actions} is @code{edit}, @code{unedit},
|
||
@code{commit}, @code{all}, or @code{none}. See
|
||
@ref{Editing files}.
|
||
|
||
@item -l
|
||
Local; run only in current working directory. See @ref{Recursive behavior}.
|
||
|
||
@item -R
|
||
Operate recursively (default). @xref{Recursive
|
||
behavior}.
|
||
@end table
|
||
|
||
@item update [@var{options}] [@var{files}@dots{}]
|
||
Bring work tree in sync with repository. See
|
||
@ref{update}.
|
||
|
||
@table @code
|
||
@item -A
|
||
Reset any sticky tags/date/options. See @ref{Sticky
|
||
tags} and @ref{Keyword substitution}.
|
||
|
||
@item -D @var{date}
|
||
Check out revisions as of @var{date} (is sticky). See
|
||
@ref{Common options}.
|
||
|
||
@item -d
|
||
Create directories. See @ref{update options}.
|
||
|
||
@item -f
|
||
Use head revision if tag/date not found. See
|
||
@ref{Common options}.
|
||
|
||
@item -I @var{ign}
|
||
More files to ignore (! to reset). See
|
||
@ref{import options}.
|
||
|
||
@c Probably want to use rev1/rev2 style like for diff
|
||
@c -r. Here and in on-line help.
|
||
@item -j @var{rev}
|
||
Merge in changes. See @ref{update options}.
|
||
|
||
@item -k @var{kflag}
|
||
Use @var{kflag} keyword expansion. See
|
||
@ref{Substitution modes}.
|
||
|
||
@item -l
|
||
Local; run only in current working directory. @xref{Recursive behavior}.
|
||
|
||
@item -P
|
||
Prune empty directories. See @ref{Moving directories}.
|
||
|
||
@item -p
|
||
Check out files to standard output (avoids
|
||
stickiness). See @ref{update options}.
|
||
|
||
@item -R
|
||
Operate recursively (default). @xref{Recursive
|
||
behavior}.
|
||
|
||
@item -r @var{tag}
|
||
Checkout revision @var{tag} (is sticky). See @ref{Common options}.
|
||
|
||
@item -W @var{spec}
|
||
More wrappers. See @ref{import options}.
|
||
@end table
|
||
|
||
@item watch [on|off|add|remove] [@var{options}] [@var{files}@dots{}]
|
||
|
||
on/off: turn on/off read-only checkouts of files. See
|
||
@ref{Setting a watch}.
|
||
|
||
add/remove: add or remove notification on actions. See
|
||
@ref{Getting Notified}.
|
||
|
||
@table @code
|
||
@item -a @var{actions}
|
||
Specify actions for temporary watch, where
|
||
@var{actions} is @code{edit}, @code{unedit},
|
||
@code{commit}, @code{all}, or @code{none}. See
|
||
@ref{Editing files}.
|
||
|
||
@item -l
|
||
Local; run only in current working directory. See @ref{Recursive behavior}.
|
||
|
||
@item -R
|
||
Operate recursively (default). @xref{Recursive
|
||
behavior}.
|
||
@end table
|
||
|
||
@item watchers [@var{options}] [@var{files}@dots{}]
|
||
See who is watching a file. See @ref{Watch information}.
|
||
|
||
@table @code
|
||
@item -l
|
||
Local; run only in current working directory. See @ref{Recursive behavior}.
|
||
|
||
@item -R
|
||
Operate recursively (default). @xref{Recursive
|
||
behavior}.
|
||
@end table
|
||
|
||
@end table
|
||
|
||
@c ---------------------------------------------------------------------
|
||
@node Administrative files
|
||
@appendix Reference manual for Administrative files
|
||
@cindex Administrative files (reference)
|
||
@cindex Files, reference manual
|
||
@cindex Reference manual (files)
|
||
@cindex CVSROOT (file)
|
||
|
||
@c FIXME? Somewhere there needs to be a more "how-to"
|
||
@c guide to writing these. I think the triggers
|
||
@c (commitinfo, loginfo, taginfo, &c) are perhaps a
|
||
@c different case than files like modules. One
|
||
@c particular issue that people sometimes are
|
||
@c (unnecessarily?) worried about is performance, and
|
||
@c the impact of writing in perl or sh or ____.
|
||
Inside the repository, in the directory
|
||
@file{$CVSROOT/CVSROOT}, there are a number of
|
||
supportive files for @sc{cvs}. You can use @sc{cvs} in a limited
|
||
fashion without any of them, but if they are set up
|
||
properly they can help make life easier. For a
|
||
discussion of how to edit them, @xref{Intro
|
||
administrative files}.
|
||
|
||
The most important of these files is the @file{modules}
|
||
file, which defines the modules inside the repository.
|
||
|
||
@menu
|
||
* modules:: Defining modules
|
||
* Wrappers:: Treat directories as files
|
||
* commit files:: The commit support files
|
||
* commitinfo:: Pre-commit checking
|
||
* verifymsg:: How are log messages evaluated?
|
||
* editinfo:: Specifying how log messages are created
|
||
(obsolete)
|
||
* loginfo:: Where should log messages be sent?
|
||
* rcsinfo:: Templates for the log messages
|
||
* cvsignore:: Ignoring files via cvsignore
|
||
* history file:: History information
|
||
* Variables:: Various variables are expanded
|
||
@end menu
|
||
|
||
@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
|
||
@node modules
|
||
@appendixsec The modules file
|
||
@cindex Modules (admin file)
|
||
@cindex Defining modules (reference manual)
|
||
|
||
The @file{modules} file records your definitions of
|
||
names for collections of source code. @sc{cvs} will
|
||
use these definitions if you use @sc{cvs} to update the
|
||
modules file (use normal commands like @code{add},
|
||
@code{commit}, etc).
|
||
|
||
The @file{modules} file may contain blank lines and
|
||
comments (lines beginning with @samp{#}) as well as
|
||
module definitions. Long lines can be continued on the
|
||
next line by specifying a backslash (@samp{\}) as the
|
||
last character on the line.
|
||
|
||
A module definition is a single line of the
|
||
@file{modules} file, in either of two formats. In both
|
||
cases, @var{mname} represents the symbolic module name,
|
||
and the remainder of the line is its definition.
|
||
|
||
@table @code
|
||
@item @var{mname} -a @var{aliases}@dots{}
|
||
This represents the simplest way of defining a module
|
||
@var{mname}. The @samp{-a} flags the definition as a
|
||
simple alias: @sc{cvs} will treat any use of @var{mname} (as
|
||
a command argument) as if the list of names
|
||
@var{aliases} had been specified instead.
|
||
@var{aliases} may contain either other module names or
|
||
paths. When you use paths in aliases, @code{checkout}
|
||
creates all intermediate directories in the working
|
||
directory, just as if the path had been specified
|
||
explicitly in the @sc{cvs} arguments.
|
||
|
||
@item @var{mname} [ options ] @var{dir} [ @var{files}@dots{} ] [ &@var{module}@dots{} ]
|
||
In the simplest case, this form of module definition
|
||
reduces to @samp{@var{mname} @var{dir}}. This defines
|
||
all the files in directory @var{dir} as module mname.
|
||
@var{dir} is a relative path (from @code{$CVSROOT}) to a
|
||
directory of source in the source repository. In this
|
||
case, on checkout, a single directory called
|
||
@var{mname} is created as a working directory; no
|
||
intermediate directory levels are used by default, even
|
||
if @var{dir} was a path involving several directory
|
||
levels.
|
||
|
||
By explicitly specifying files in the module definition
|
||
after @var{dir}, you can select particular files from
|
||
directory @var{dir}. The sample definition for
|
||
@samp{modules} is an example of a module defined with a
|
||
single file from a particular directory. Here is
|
||
another example:
|
||
|
||
@example
|
||
m4test unsupported/gnu/m4 foreach.m4 forloop.m4
|
||
@end example
|
||
|
||
@noindent
|
||
With this definition, executing @samp{cvs checkout
|
||
m4test} will create a single working directory
|
||
@file{m4test} containing the two files listed, which
|
||
both come from a common directory several levels deep
|
||
in the @sc{cvs} source repository.
|
||
|
||
A module definition can refer to other modules by
|
||
including @samp{&@var{module}} in its definition.
|
||
@code{checkout} creates a subdirectory for each such
|
||
module, in the directory containing the module. For
|
||
example, if modules contains
|
||
|
||
@example
|
||
m4test &unsupported
|
||
@end example
|
||
|
||
then a checkout will create an @code{m4test} directory
|
||
which contains a directory called @code{unsupported},
|
||
which in turns contains all the directories and files
|
||
which live there.
|
||
@c FIXME: this is hard to describe since we don't tell
|
||
@c the user what the repository contains. Best way to
|
||
@c fix this whole mess is an extended example where we
|
||
@c first say what is in the repository, then show a
|
||
@c regular module, an alias module, and an & module.
|
||
@c We should mention the concept of options only
|
||
@c *after* we've taken care of those basics.
|
||
@c
|
||
@c FIXCVS: What happens if regular and & modules are
|
||
@c combined, as in "ampermodule first-dir &second-dir"?
|
||
@c When I tried it, it seemed to just ignore the
|
||
@c "first-dir". I think perhaps it should be an error
|
||
@c (but this needs further investigation).
|
||
@c In addition to discussing what each one does, we
|
||
@c should put in a few words about why you would use one or
|
||
@c the other in various situations.
|
||
|
||
@table @code
|
||
@item -d @var{name}
|
||
Name the working directory something other than the
|
||
module name.
|
||
|
||
@cindex Export program
|
||
@item -e @var{prog}
|
||
Specify a program @var{prog} to run whenever files in a
|
||
module are exported. @var{prog} runs with a single
|
||
argument, the module name.
|
||
@c FIXME: Is it run on server? client?
|
||
|
||
@cindex Checkin program
|
||
@item -i @var{prog}
|
||
Specify a program @var{prog} to run whenever files in a
|
||
module are committed. @var{prog} runs with a single
|
||
argument, the full pathname of the affected directory
|
||
in a source repository. The @file{commitinfo},
|
||
@file{loginfo}, and @file{verifymsg} files provide other
|
||
ways to call a program on commit.
|
||
@c FIXME: Is it run on server? client?
|
||
|
||
@cindex Checkout program
|
||
@item -o @var{prog}
|
||
Specify a program @var{prog} to run whenever files in a
|
||
module are checked out. @var{prog} runs with a single
|
||
argument, the module name.
|
||
@c FIXME: Is it run on server? client?
|
||
|
||
@cindex Status of a module
|
||
@cindex Module status
|
||
@item -s @var{status}
|
||
Assign a status to the module. When the module file is
|
||
printed with @samp{cvs checkout -s} the modules are
|
||
sorted according to primarily module status, and
|
||
secondarily according to the module name. This option
|
||
has no other meaning. You can use this option for
|
||
several things besides status: for instance, list the
|
||
person that is responsible for this module.
|
||
|
||
@cindex Tag program
|
||
@item -t @var{prog}
|
||
Specify a program @var{prog} to run whenever files in a
|
||
module are tagged with @code{rtag}. @var{prog} runs
|
||
with two arguments: the module name and the symbolic
|
||
tag specified to @code{rtag}. There is no way to
|
||
specify a program to run when @code{tag} is executed.
|
||
@c FIXME: Is it run on server? client?
|
||
|
||
@cindex Update program
|
||
@item -u @var{prog}
|
||
Specify a program @var{prog} to run whenever @samp{cvs
|
||
update} is executed from the top-level directory of the
|
||
checked-out module. @var{prog} runs with a single
|
||
argument, the full path to the source repository for
|
||
this module.
|
||
@c FIXME: Is it run on server? client?
|
||
@end table
|
||
@end table
|
||
|
||
@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
|
||
@node Wrappers
|
||
@appendixsec The cvswrappers file
|
||
@cindex cvswrappers (admin file)
|
||
@cindex CVSWRAPPERS, environment variable
|
||
@cindex Wrappers
|
||
|
||
@c FIXME: need some better way of separating this out
|
||
@c by functionality. -t/-f is one feature, -m is
|
||
@c another, and -k is a third. And this discussion
|
||
@c should be better motivated (e.g. start with the
|
||
@c problems, then explain how the feature solves it).
|
||
|
||
Wrappers allow you to set a hook which transforms files on
|
||
their way in and out of @sc{cvs}.
|
||
|
||
The file @file{cvswrappers} defines the script that will be
|
||
run on a file when its name matches a regular
|
||
expresion. There are two scripts that can be run on a
|
||
file or directory. One script is executed on the file/directory
|
||
before being checked into the repository (this is denoted
|
||
with the @code{-t} flag) and the other when the file is
|
||
checked out of the repository (this is denoted with the
|
||
@code{-f} flag). The @samp{-t}/@samp{-f} feature does
|
||
not work with client/server @sc{cvs}.
|
||
|
||
The @file{cvswrappers} also has a @samp{-m} option to
|
||
specify the merge methodology that should be used when
|
||
the file is updated. @code{MERGE} means the usual
|
||
@sc{cvs} behavior: try to merge the files (this
|
||
generally will not work for binary files). @code{COPY}
|
||
means that @code{cvs update} will merely copy one
|
||
version over the other, and require the user using
|
||
mechanisms outside @sc{cvs}, to insert any necessary
|
||
changes.
|
||
@c FIXME: which version is copied over which version?
|
||
The @samp{-m} wrapper option only affects behavior when
|
||
merging is done on update; it does not affect how files
|
||
are stored. See @xref{Binary files}, for more on
|
||
binary files.
|
||
|
||
The basic format of the file @file{cvswrappers} is:
|
||
|
||
@c FIXME: @example is all wrong for this. Use @deffn or
|
||
@c something more sensible.
|
||
@example
|
||
wildcard [option value][option value]...
|
||
|
||
where option is one of
|
||
-f from cvs filter value: path to filter
|
||
-t to cvs filter value: path to filter
|
||
-m update methodology value: MERGE or COPY
|
||
-k keyword expansion value: expansion mode
|
||
|
||
and value is a single-quote delimited value.
|
||
@end example
|
||
|
||
@example
|
||
*.nib -f 'unwrap %s' -t 'wrap %s %s' -m 'COPY'
|
||
*.c -t 'indent %s %s'
|
||
@end example
|
||
|
||
@noindent
|
||
The above example of a @file{cvswrappers} file
|
||
states that all files/directories that end with a @code{.nib}
|
||
should be filtered with the @file{wrap} program before
|
||
checking the file into the repository. The file should
|
||
be filtered though the @file{unwrap} program when the
|
||
file is checked out of the repository. The
|
||
@file{cvswrappers} file also states that a @code{COPY}
|
||
methodology should be used when updating the files in
|
||
the repository (that is no merging should be performed).
|
||
|
||
@c What pitfalls arise when using indent this way? Is
|
||
@c it a winning thing to do? Would be nice to at least
|
||
@c hint at those issues; we want our examples to tell
|
||
@c how to solve problems, not just to say that cvs can
|
||
@c do certain things.
|
||
The last example line says that all files that end with
|
||
a @code{*.c} should be filtered with @file{indent}
|
||
before being checked into the repository. Unlike the previous
|
||
example no filtering of the @code{*.c} file is done when
|
||
it is checked out of the repository.
|
||
@noindent
|
||
The @code{-t} filter is called with two arguments,
|
||
the first is the name of the file/directory to filter
|
||
and the second is the pathname to where the resulting
|
||
filtered file should be placed.
|
||
|
||
@noindent
|
||
The @code{-f} filter is called with one argument,
|
||
which is the name of the file to filter from. The end
|
||
result of this filter will be a file in the users directory
|
||
that they can work on as they normally would.
|
||
|
||
Note that the @samp{-t}/@samp{-f} features do not
|
||
conveniently handle one portion of CVS's operation:
|
||
determining when files are modified. CVS will still
|
||
want a file (or directory) to exist, and it will use
|
||
its modification time to determine whether a file is
|
||
modified. If CVS erroneously thinks a file is
|
||
unmodified (for example, a directory is unchanged but
|
||
one of the files within it is changed), you can force
|
||
it to check in the file anyway by specifying the
|
||
@samp{-f} option to @code{cvs commit} (@pxref{commit
|
||
options}).
|
||
@c This is, of course, a serious design flaw in -t/-f.
|
||
@c Probably the whole functionality needs to be
|
||
@c redesigned (starting from requirements) to fix this.
|
||
|
||
For another example, the following command imports a
|
||
directory, treating files whose name ends in
|
||
@samp{.exe} as binary:
|
||
|
||
@example
|
||
cvs import -I ! -W "*.exe -k 'b'" first-dir vendortag reltag
|
||
@end example
|
||
|
||
@c Another good example, would be storing files
|
||
@c (e.g. binary files) compressed in the repository.
|
||
@c ::::::::::::::::::
|
||
@c cvswrappers
|
||
@c ::::::::::::::::::
|
||
@c *.t12 -m 'COPY'
|
||
@c *.t[0-9][0-9] -f 'gunzipcp %s' -t 'gzipcp %s %s' -m 'COPY'
|
||
@c
|
||
@c ::::::::::::::::::
|
||
@c gunzipcp
|
||
@c ::::::::::::::::::
|
||
@c :
|
||
@c [ -f $1 ] || exit 1
|
||
@c zcat $1 > /tmp/.#$1.$$
|
||
@c mv /tmp/.#$1.$$ $1
|
||
@c
|
||
@c ::::::::::::::::::
|
||
@c gzipcp
|
||
@c ::::::::::::::::::
|
||
@c :
|
||
@c DIRNAME=`echo $1 | sed -e "s|/.*/||g"`
|
||
@c if [ ! -d $DIRNAME ] ; then
|
||
@c DIRNAME=`echo $1 | sed -e "s|.*/||g"`
|
||
@c fi
|
||
@c gzip -c $DIRNAME > $2
|
||
@c One catch--"cvs diff" will not invoke the wrappers
|
||
@c (probably a CVS bug, although I haven't thought it out).
|
||
|
||
@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
|
||
@node commit files
|
||
@appendixsec The commit support files
|
||
@cindex Commit files
|
||
|
||
The @samp{-i} flag in the @file{modules} file can be
|
||
used to run a certain program whenever files are
|
||
committed (@pxref{modules}). The files described in
|
||
this section provide other, more flexible, ways to run
|
||
programs whenever something is committed.
|
||
|
||
There are three kind of programs that can be run on
|
||
commit. They are specified in files in the repository,
|
||
as described below. The following table summarizes the
|
||
file names and the purpose of the corresponding
|
||
programs.
|
||
|
||
@table @file
|
||
@item commitinfo
|
||
The program is responsible for checking that the commit
|
||
is allowed. If it exits with a non-zero exit status
|
||
the commit will be aborted.
|
||
|
||
@item verifymsg
|
||
The specified program is used to evaluate the log message,
|
||
and possibly verify that it contains all required
|
||
fields. This is most useful in combination with the
|
||
@file{rcsinfo} file, which can hold a log message
|
||
template (@pxref{rcsinfo}).
|
||
|
||
@item editinfo
|
||
The specified program is used to edit the log message,
|
||
and possibly verify that it contains all required
|
||
fields. This is most useful in combination with the
|
||
@file{rcsinfo} file, which can hold a log message
|
||
template (@pxref{rcsinfo}). (obsolete)
|
||
|
||
@item loginfo
|
||
The specified program is called when the commit is
|
||
complete. It receives the log message and some
|
||
additional information and can store the log message in
|
||
a file, or mail it to appropriate persons, or maybe
|
||
post it to a local newsgroup, or@dots{} Your
|
||
imagination is the limit!
|
||
@end table
|
||
|
||
@menu
|
||
* syntax:: The common syntax
|
||
@end menu
|
||
|
||
@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
|
||
@node syntax
|
||
@appendixsubsec The common syntax
|
||
@cindex Info files (syntax)
|
||
@cindex Syntax of info files
|
||
@cindex Common syntax of info files
|
||
|
||
@c FIXME: having this so totally separate from the
|
||
@c Variables node is rather bogus.
|
||
|
||
The administrative files such as @file{commitinfo},
|
||
@file{loginfo}, @file{rcsinfo}, @file{verifymsg}, etc.,
|
||
all have a common format. The purpose of the files are
|
||
described later on. The common syntax is described
|
||
here.
|
||
|
||
@cindex regular expression syntax
|
||
Each line contains the following:
|
||
@itemize @bullet
|
||
@item
|
||
@c Say anything about DEFAULT and ALL? Right now we
|
||
@c leave that to the description of each file (and in fact
|
||
@c the practice is inconsistent which is really annoying).
|
||
A regular expression. This is a basic regular
|
||
expression in the syntax used by GNU emacs.
|
||
@c FIXME: What we probably should be saying is "POSIX Basic
|
||
@c Regular Expression with the following extensions (`\('
|
||
@c `\|' '+' etc)"
|
||
@c rather than define it with reference to emacs.
|
||
@c The reference to emacs is not strictly speaking
|
||
@c true, as we don't support \=, \s, or \S. Also it isn't
|
||
@c clear we should document and/or promise to continue to
|
||
@c support all the obscure emacs extensions like \<.
|
||
@c Also need to better cite (or include) full
|
||
@c documentation for the syntax.
|
||
|
||
@item
|
||
A whitespace separator---one or more spaces and/or tabs.
|
||
|
||
@item
|
||
A file name or command-line template.
|
||
@end itemize
|
||
|
||
@noindent
|
||
Blank lines are ignored. Lines that start with the
|
||
character @samp{#} are treated as comments. Long lines
|
||
unfortunately can @emph{not} be broken in two parts in
|
||
any way.
|
||
|
||
The first regular expression that matches the current
|
||
directory name in the repository is used. The rest of the line
|
||
is used as a file name or command-line as appropriate.
|
||
|
||
@c FIXME: need an example. In particular, show what
|
||
@c the regular expression is matched against (one
|
||
@c ordinarily clueful person got confused about whether it
|
||
@c includes the filename--"directory name" above should be
|
||
@c unambiguous but there is nothing like an example to
|
||
@c confirm people's understanding of this sort of thing).
|
||
|
||
@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
|
||
@node commitinfo
|
||
@appendixsec Commitinfo
|
||
@cindex Commitinfo
|
||
@cindex Checking commits
|
||
@cindex Precommit checking
|
||
|
||
The @file{commitinfo} file defines programs to execute
|
||
whenever @samp{cvs commit} is about to execute. These
|
||
programs are used for pre-commit checking to verify
|
||
that the modified, added and removed files are really
|
||
ready to be committed. This could be used, for
|
||
instance, to verify that the changed files conform to
|
||
to your site's standards for coding practice.
|
||
|
||
As mentioned earlier, each line in the
|
||
@file{commitinfo} file consists of a regular expression
|
||
and a command-line template. The template can include
|
||
a program name and any number of arguments you wish to
|
||
supply to it. The full path to the current source
|
||
repository is appended to the template, followed by the
|
||
file names of any files involved in the commit (added,
|
||
removed, and modified files).
|
||
|
||
@cindex exit status, of commitinfo
|
||
The first line with a regular expression matching the
|
||
relative path to the module will be used. If the
|
||
command returns a non-zero exit status the commit will
|
||
be aborted.
|
||
|
||
@cindex DEFAULT in commitinfo
|
||
If the repository name does not match any of the
|
||
regular expressions in this file, the @samp{DEFAULT}
|
||
line is used, if it is specified.
|
||
|
||
@cindex ALL in commitinfo
|
||
All occurances of the name @samp{ALL} appearing as a
|
||
regular expression are used in addition to the first
|
||
matching regular expression or the name @samp{DEFAULT}.
|
||
|
||
Note: when @sc{CVS} is accessing a remote repository,
|
||
@file{commitinfo} will be run on the @emph{remote}
|
||
(i.e., server) side, not the client side (@pxref{Remote
|
||
repositories}).
|
||
|
||
@c FIXME: should discuss using commitinfo to control
|
||
@c who has checkin access to what (e.g. Joe can check into
|
||
@c directories a, b, and c, and Mary can check into
|
||
@c directories b, c, and d--note this case cannot be
|
||
@c conveniently handled with unix groups). Of course,
|
||
@c adding a new set of features to CVS might be a more
|
||
@c natural way to fix this problem than telling people to
|
||
@c use commitinfo.
|
||
@c FIXME: Should make some reference, especially in
|
||
@c the context of controlling who has access, to the fact
|
||
@c that commitinfo can be circumvented. Perhaps
|
||
@c mention SETXID (but has it been carefully examined
|
||
@c for holes?). This fits in with the discussion of
|
||
@c general CVS security in "Password authentication
|
||
@c security" (the bit which is not pserver-specific).
|
||
|
||
@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
|
||
@node verifymsg
|
||
@appendixsec Verifying log messages
|
||
@cindex verifymsg (admin file)
|
||
@cindex log message, verifying
|
||
|
||
Once you have entered a log message, you can evaluate
|
||
that message to check for specific content, such as
|
||
a bug ID. Use the @file{verifymsg} file to
|
||
specify a program that is used to verify the log message.
|
||
This program could be a simple script that checks
|
||
that the entered message contains the required fields.
|
||
|
||
The @file{verifymsg} file is often most useful together
|
||
with the @file{rcsinfo} file, which can be used to
|
||
specify a log message template.
|
||
|
||
Each line in the @file{verifymsg} file consists of a
|
||
regular expression and a command-line template. The
|
||
template must include a program name, and can include
|
||
any number of arguments. The full path to the current
|
||
log message template file is appended to the template.
|
||
|
||
One thing that should be noted is that the @samp{ALL}
|
||
keyword is not supported. If more than one matching
|
||
line is found, the first one is used. This can be
|
||
useful for specifying a default verification script in a
|
||
module, and then overriding it in a subdirectory.
|
||
|
||
@cindex DEFAULT in verifymsg
|
||
If the repository name does not match any of the
|
||
regular expressions in this file, the @samp{DEFAULT}
|
||
line is used, if it is specified.
|
||
|
||
@cindex exit status, of verifymsg
|
||
If the verification script exits with a non-zero exit status,
|
||
the commit is aborted.
|
||
|
||
Note that the verification script cannot change the log
|
||
message; it can merely accept it or reject it.
|
||
@c FIXME? Is this an annoying limitation? It would be
|
||
@c relatively easy to fix (although it would *not* be a
|
||
@c good idea for a verifymsg script to interact with the user
|
||
@c at least in the client/server case because of locks
|
||
@c and all that jazz).
|
||
|
||
The following is a little silly example of a
|
||
@file{verifymsg} file, together with the corresponding
|
||
@file{rcsinfo} file, the log message template and an
|
||
verification script. We begin with the log message template.
|
||
We want to always record a bug-id number on the first
|
||
line of the log message. The rest of log message is
|
||
free text. The following template is found in the file
|
||
@file{/usr/cvssupport/tc.template}.
|
||
|
||
@example
|
||
BugId:
|
||
@end example
|
||
|
||
The script @file{/usr/cvssupport/bugid.verify} is used to
|
||
evaluate the log message.
|
||
|
||
@example
|
||
#!/bin/sh
|
||
#
|
||
# bugid.verify filename
|
||
#
|
||
# Verify that the log message contains a valid bugid
|
||
# on the first line.
|
||
#
|
||
if head -1 < $1 | grep '^BugId:[ ]*[0-9][0-9]*$' > /dev/null; then
|
||
exit 0
|
||
else
|
||
echo "No BugId found."
|
||
exit 1
|
||
fi
|
||
@end example
|
||
|
||
The @file{verifymsg} file contains this line:
|
||
|
||
@example
|
||
^tc /usr/cvssupport/bugid.edit
|
||
@end example
|
||
|
||
The @file{rcsinfo} file contains this line:
|
||
|
||
@example
|
||
^tc /usr/cvssupport/tc.template
|
||
@end example
|
||
|
||
|
||
|
||
@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
|
||
@node editinfo
|
||
@appendixsec Editinfo
|
||
@cindex editinfo (admin file)
|
||
@cindex Editor, specifying per module
|
||
@cindex Per-module editor
|
||
@cindex Log messages, editing
|
||
|
||
@emph{NOTE:} The @file{editinfo} feature has been
|
||
rendered obsolete. To set a default editor for log
|
||
messages use the @code{EDITOR} environment variable
|
||
(@pxref{Environment variables}) or the @samp{-e} global
|
||
option (@pxref{Global options}). See @ref{verifymsg},
|
||
for information on the use of the @file{verifymsg}
|
||
feature for evaluating log messages.
|
||
|
||
If you want to make sure that all log messages look the
|
||
same way, you can use the @file{editinfo} file to
|
||
specify a program that is used to edit the log message.
|
||
This program could be a custom-made editor that always
|
||
enforces a certain style of the log message, or maybe a
|
||
simple shell script that calls an editor, and checks
|
||
that the entered message contains the required fields.
|
||
|
||
If no matching line is found in the @file{editinfo}
|
||
file, the editor specified in the environment variable
|
||
@code{$CVSEDITOR} is used instead. If that variable is
|
||
not set, then the environment variable @code{$EDITOR}
|
||
is used instead. If that variable is not
|
||
set a default will be used. See @ref{Committing your changes}.
|
||
|
||
The @file{editinfo} file is often most useful together
|
||
with the @file{rcsinfo} file, which can be used to
|
||
specify a log message template.
|
||
|
||
Each line in the @file{editinfo} file consists of a
|
||
regular expression and a command-line template. The
|
||
template must include a program name, and can include
|
||
any number of arguments. The full path to the current
|
||
log message template file is appended to the template.
|
||
|
||
One thing that should be noted is that the @samp{ALL}
|
||
keyword is not supported. If more than one matching
|
||
line is found, the first one is used. This can be
|
||
useful for specifying a default edit script in a
|
||
module, and then overriding it in a subdirectory.
|
||
|
||
@cindex DEFAULT in editinfo
|
||
If the repository name does not match any of the
|
||
regular expressions in this file, the @samp{DEFAULT}
|
||
line is used, if it is specified.
|
||
|
||
If the edit script exits with a non-zero exit status,
|
||
the commit is aborted.
|
||
|
||
Note: when @sc{CVS} is accessing a remote repository,
|
||
or when the @samp{-m} or @samp{-F} options to @code{cvs
|
||
commit} are used, @file{editinfo} will not be consulted.
|
||
There is no good workaround for this; use
|
||
@file{verifymsg} instead.
|
||
|
||
@menu
|
||
* editinfo example:: Editinfo example
|
||
@end menu
|
||
|
||
@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
|
||
@node editinfo example
|
||
@appendixsubsec Editinfo example
|
||
|
||
The following is a little silly example of a
|
||
@file{editinfo} file, together with the corresponding
|
||
@file{rcsinfo} file, the log message template and an
|
||
editor script. We begin with the log message template.
|
||
We want to always record a bug-id number on the first
|
||
line of the log message. The rest of log message is
|
||
free text. The following template is found in the file
|
||
@file{/usr/cvssupport/tc.template}.
|
||
|
||
@example
|
||
BugId:
|
||
@end example
|
||
|
||
The script @file{/usr/cvssupport/bugid.edit} is used to
|
||
edit the log message.
|
||
|
||
@example
|
||
#!/bin/sh
|
||
#
|
||
# bugid.edit filename
|
||
#
|
||
# Call $EDITOR on FILENAME, and verify that the
|
||
# resulting file contains a valid bugid on the first
|
||
# line.
|
||
if [ "x$EDITOR" = "x" ]; then EDITOR=vi; fi
|
||
if [ "x$CVSEDITOR" = "x" ]; then CVSEDITOR=$EDITOR; fi
|
||
$CVSEDITOR $1
|
||
until head -1|grep '^BugId:[ ]*[0-9][0-9]*$' < $1
|
||
do echo -n "No BugId found. Edit again? ([y]/n)"
|
||
read ans
|
||
case $@{ans@} in
|
||
n*) exit 1;;
|
||
esac
|
||
$CVSEDITOR $1
|
||
done
|
||
@end example
|
||
|
||
The @file{editinfo} file contains this line:
|
||
|
||
@example
|
||
^tc /usr/cvssupport/bugid.edit
|
||
@end example
|
||
|
||
The @file{rcsinfo} file contains this line:
|
||
|
||
@example
|
||
^tc /usr/cvssupport/tc.template
|
||
@end example
|
||
|
||
@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
|
||
@node loginfo
|
||
@appendixsec Loginfo
|
||
@cindex loginfo (admin file)
|
||
@cindex Storing log messages
|
||
@cindex Mailing log messages
|
||
@cindex Distributing log messages
|
||
@cindex Log messages
|
||
|
||
The @file{loginfo} file is used to control where
|
||
@samp{cvs commit} log information is sent. The first
|
||
entry on a line is a regular expression which is tested
|
||
against the directory that the change is being made to,
|
||
relative to the @code{$CVSROOT}. If a match is found, then
|
||
the remainder of the line is a filter program that
|
||
should expect log information on its standard input.
|
||
|
||
If the repository name does not match any of the
|
||
regular expressions in this file, the @samp{DEFAULT}
|
||
line is used, if it is specified.
|
||
|
||
All occurances of the name @samp{ALL} appearing as a
|
||
regular expression are used in addition to the first
|
||
matching regular expression or @samp{DEFAULT}.
|
||
|
||
The first matching regular expression is used.
|
||
|
||
@xref{commit files}, for a description of the syntax of
|
||
the @file{loginfo} file.
|
||
|
||
The user may specify a format string as
|
||
part of the filter. The string is composed of a
|
||
@samp{%} followed by a space, or followed by a single
|
||
format character, or followed by a set of format
|
||
characters surrounded by @samp{@{} and @samp{@}} as
|
||
separators. The format characters are:
|
||
|
||
@table @t
|
||
@item s
|
||
file name
|
||
@item V
|
||
old version number (pre-checkin)
|
||
@item v
|
||
new version number (post-checkin)
|
||
@end table
|
||
|
||
All other characters that appear in a format string
|
||
expand to an empty field (commas separating fields are
|
||
still provided).
|
||
|
||
For example, some valid format strings are @samp{%},
|
||
@samp{%s}, @samp{%@{s@}}, and @samp{%@{sVv@}}.
|
||
|
||
The output will be a string of tokens separated by
|
||
spaces. For backwards compatibility, the the first
|
||
token will be the repository name. The rest of the
|
||
tokens will be comma-delimited lists of the information
|
||
requested in the format string. For example, if
|
||
@samp{/u/src/master} is the repository, @samp{%@{sVv@}}
|
||
is the format string, and three files (@t{ChangeLog},
|
||
@t{Makefile}, @t{foo.c}) were modified, the output
|
||
might be:
|
||
|
||
@example
|
||
/u/src/master ChangeLog,1.1,1.2 Makefile,1.3,1.4 foo.c,1.12,1.13
|
||
@end example
|
||
|
||
As another example, @samp{%@{@}} means that only the
|
||
name of the repository will be generated.
|
||
|
||
Note: when @sc{CVS} is accessing a remote repository,
|
||
@file{loginfo} will be run on the @emph{remote}
|
||
(i.e., server) side, not the client side (@pxref{Remote
|
||
repositories}).
|
||
|
||
@menu
|
||
* loginfo example:: Loginfo example
|
||
* Keeping a checked out copy:: Updating a tree on every checkin
|
||
@end menu
|
||
|
||
@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
|
||
@node loginfo example
|
||
@appendixsubsec Loginfo example
|
||
|
||
The following @file{loginfo} file, together with the
|
||
tiny shell-script below, appends all log messages
|
||
to the file @file{$CVSROOT/CVSROOT/commitlog},
|
||
and any commits to the administrative files (inside
|
||
the @file{CVSROOT} directory) are also logged in
|
||
@file{/usr/adm/cvsroot-log}.
|
||
@c and mailed to @t{ceder}.
|
||
|
||
@c FIXME: is it a CVS feature or bug that only the
|
||
@c first matching line is used? It is documented
|
||
@c above, but is it useful? This example (with the
|
||
@c mail to ceder put back in) is awkward to write if
|
||
@c only the first matching line is used.
|
||
@example
|
||
ALL /usr/local/bin/cvs-log $CVSROOT/CVSROOT/commitlog
|
||
@c ^CVSROOT Mail -s %s ceder
|
||
^CVSROOT /usr/local/bin/cvs-log /usr/adm/cvsroot-log
|
||
@end example
|
||
|
||
The shell-script @file{/usr/local/bin/cvs-log} looks
|
||
like this:
|
||
|
||
@example
|
||
#!/bin/sh
|
||
(echo "------------------------------------------------------";
|
||
echo -n $USER" ";
|
||
date;
|
||
echo;
|
||
sed '1s+'$@{CVSROOT@}'++') >> $1
|
||
@end example
|
||
|
||
@node Keeping a checked out copy
|
||
@appendixsubsec Keeping a checked out copy
|
||
|
||
@c What other index entries? It seems like
|
||
@c people might want to use a lot of different
|
||
@c words for this functionality.
|
||
@cindex keeping a checked out copy
|
||
@cindex checked out copy, keeping
|
||
@cindex web pages, maintaining with CVS
|
||
|
||
It is often useful to maintain a directory tree which
|
||
contains files which correspond to the latest version
|
||
in the repository. For example, other developers might
|
||
want to refer to the latest sources without having to
|
||
check them out, or you might be maintaining a web site
|
||
with @sc{cvs} and want every checkin to cause the files
|
||
used by the web server to be updated.
|
||
@c Can we offer more details on the web example? Or
|
||
@c point the user at how to figure it out? This text
|
||
@c strikes me as sufficient for someone who already has
|
||
@c some idea of what we mean but not enough for the naive
|
||
@c user/sysadmin to understand it and set it up.
|
||
|
||
The way to do this is by having loginfo invoke
|
||
@code{cvs update}. Doing so in the naive way will
|
||
cause a problem with locks, so the @code{cvs update}
|
||
must be run in the background.
|
||
@c Should we try to describe the problem with locks?
|
||
@c It seems like a digression for someone who just
|
||
@c wants to know how to make it work.
|
||
@c Another choice which might work for a single file
|
||
@c is to use "cvs -n update -p" which doesn't take
|
||
@c out locks (I think) but I don't see many advantages
|
||
@c of that and we might as well document something which
|
||
@c works for multiple files.
|
||
Here is an example (this should all be on one line):
|
||
|
||
@example
|
||
^cyclic-pages (date; cat; (sleep 2; cd /u/www/local-docs;
|
||
cvs -q update -d) &) >> $CVSROOT/CVSROOT/updatelog 2>&1
|
||
@end example
|
||
|
||
This will cause checkins to repository directories
|
||
starting with @code{cyclic-pages} to update the checked
|
||
out tree in @file{/u/www/local-docs}.
|
||
@c More info on some of the details? The "sleep 2" is
|
||
@c so if we are lucky the lock will be gone by the time
|
||
@c we start and we can wait 2 seconds instead of 30.
|
||
|
||
@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
|
||
@node rcsinfo
|
||
@appendixsec Rcsinfo
|
||
@cindex rcsinfo (admin file)
|
||
@cindex Form for log message
|
||
@cindex Log message template
|
||
@cindex Template for log message
|
||
|
||
The @file{rcsinfo} file can be used to specify a form to
|
||
edit when filling out the commit log. The
|
||
@file{rcsinfo} file has a syntax similar to the
|
||
@file{verifymsg}, @file{commitinfo} and @file{loginfo}
|
||
files. @xref{syntax}. Unlike the other files the second
|
||
part is @emph{not} a command-line template. Instead,
|
||
the part after the regular expression should be a full pathname to
|
||
a file containing the log message template.
|
||
|
||
If the repository name does not match any of the
|
||
regular expressions in this file, the @samp{DEFAULT}
|
||
line is used, if it is specified.
|
||
|
||
All occurances of the name @samp{ALL} appearing as a
|
||
regular expression are used in addition to the first
|
||
matching regular expression or @samp{DEFAULT}.
|
||
|
||
@c FIXME: should be offering advice, somewhere around
|
||
@c here, about where to put the template file. The
|
||
@c verifymsg example uses /usr/cvssupport but doesn't
|
||
@c say anything about what that directory is for or
|
||
@c whether it is hardwired into CVS or who creates
|
||
@c it or anything. In particular we should say
|
||
@c how to version control the template file. A
|
||
@c probably better answer than the /usr/cvsssupport
|
||
@c stuff is to use checkoutlist. FIXME: it doesn't
|
||
@c seem like checkoutlist is documented at all!
|
||
@c Also I am starting to see a connection between
|
||
@c this and the Keeping a checked out copy node.
|
||
@c Probably want to say something about that.
|
||
The log message template will be used as a default log
|
||
message. If you specify a log message with @samp{cvs
|
||
commit -m @var{message}} or @samp{cvs commit -f
|
||
@var{file}} that log message will override the
|
||
template.
|
||
|
||
@xref{verifymsg}, for an example @file{rcsinfo}
|
||
file.
|
||
|
||
When @sc{CVS} is accessing a remote repository,
|
||
the contents of @file{rcsinfo} at the time a directory
|
||
is first checked out will specify a template which does
|
||
not then change. If you edit @file{rcsinfo} or its
|
||
templates, you may need to check out a new working
|
||
directory.
|
||
@c Would be nice to fix CVS so this isn't needed. For
|
||
@c example, a mechanism analogous to CVS/Entries, where
|
||
@c the client keeps track of what version of the template
|
||
@c it has.
|
||
|
||
@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
|
||
@node cvsignore
|
||
@appendixsec Ignoring files via cvsignore
|
||
@cindex cvsignore (admin file), global
|
||
@cindex Global cvsignore
|
||
@cindex Ignoring files
|
||
@c -- This chapter should maybe be moved to the
|
||
@c tutorial part of the manual?
|
||
|
||
There are certain file names that frequently occur
|
||
inside your working copy, but that you don't want to
|
||
put under @sc{cvs} control. Examples are all the object
|
||
files that you get while you compile your sources.
|
||
Normally, when you run @samp{cvs update}, it prints a
|
||
line for each file it encounters that it doesn't know
|
||
about (@pxref{update output}).
|
||
|
||
@sc{cvs} has a list of files (or sh(1) file name patterns)
|
||
that it should ignore while running @code{update},
|
||
@code{import} and @code{release}.
|
||
@c -- Are those the only three commands affected?
|
||
This list is constructed in the following way.
|
||
|
||
@itemize @bullet
|
||
@item
|
||
The list is initialized to include certain file name
|
||
patterns: names associated with @sc{cvs}
|
||
administration, or with other common source control
|
||
systems; common names for patch files, object files,
|
||
archive files, and editor backup files; and other names
|
||
that are usually artifacts of assorted utilities.
|
||
Currently, the default list of ignored file name
|
||
patterns is:
|
||
|
||
@cindex Ignored files
|
||
@cindex Automatically ignored files
|
||
@example
|
||
RCS SCCS CVS CVS.adm
|
||
RCSLOG cvslog.*
|
||
tags TAGS
|
||
.make.state .nse_depinfo
|
||
*~ #* .#* ,* _$* *$
|
||
*.old *.bak *.BAK *.orig *.rej .del-*
|
||
*.a *.olb *.o *.obj *.so *.exe
|
||
*.Z *.elc *.ln
|
||
core
|
||
@end example
|
||
|
||
@item
|
||
The per-repository list in
|
||
@file{$CVSROOT/CVSROOT/cvsignore} is appended to
|
||
the list, if that file exists.
|
||
|
||
@item
|
||
The per-user list in @file{.cvsignore} in your home
|
||
directory is appended to the list, if it exists.
|
||
|
||
@item
|
||
Any entries in the environment variable
|
||
@code{$CVSIGNORE} is appended to the list.
|
||
|
||
@item
|
||
Any @samp{-I} options given to @sc{cvs} is appended.
|
||
|
||
@item
|
||
As @sc{cvs} traverses through your directories, the contents
|
||
of any @file{.cvsignore} will be appended to the list.
|
||
The patterns found in @file{.cvsignore} are only valid
|
||
for the directory that contains them, not for
|
||
any sub-directories.
|
||
@end itemize
|
||
|
||
In any of the 5 places listed above, a single
|
||
exclamation mark (@samp{!}) clears the ignore list.
|
||
This can be used if you want to store any file which
|
||
normally is ignored by @sc{cvs}.
|
||
|
||
Specifying @samp{-I !} to @code{cvs import} will import
|
||
everything, which is generally what you want to do if
|
||
you are importing files from a pristine distribution or
|
||
any other source which is known to not contain any
|
||
extraneous files. However, looking at the rules above
|
||
you will see there is a fly in the ointment; if the
|
||
distribution contains any @file{.cvsignore} files, then
|
||
the patterns from those files will be processed even if
|
||
@samp{-I !} is specified. The only workaround is to
|
||
remove the @file{.cvsignore} files in order to do the
|
||
import. Because this is awkward, in the future
|
||
@samp{-I !} might be modified to override
|
||
@file{.cvsignore} files in each directory.
|
||
|
||
@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
|
||
@node history file
|
||
@appendixsec The history file
|
||
@cindex History file
|
||
@cindex Log information, saving
|
||
|
||
The file @file{$CVSROOT/CVSROOT/history} is used
|
||
to log information for the @code{history} command
|
||
(@pxref{history}). This file must be created to turn
|
||
on logging. This is done automatically if the
|
||
@code{cvs init} command is used to set up the
|
||
repository (@pxref{Creating a repository}).
|
||
|
||
The file format of the @file{history} file is
|
||
documented only in comments in the @sc{cvs} source
|
||
code, but generally programs should use the @code{cvs
|
||
history} command to access it anyway, in case the
|
||
format changes with future releases of @sc{cvs}.
|
||
|
||
@node Variables
|
||
@appendixsec Expansions in administrative files
|
||
|
||
Sometimes in writing an administrative file, you might
|
||
want the file to be able to know various things based
|
||
on environment @sc{cvs} is running in. There are
|
||
several mechanisms to do that.
|
||
|
||
To find the home directory of the user running @sc{cvs}
|
||
(from the @code{HOME} environment variable), use
|
||
@samp{~} followed by @samp{/} or the end of the line.
|
||
Likewise for the home directory of @var{user}, use
|
||
@samp{~@var{user}}. These variables are expanded on
|
||
the server machine, and don't get any resonable
|
||
expansion if pserver (@pxref{Password authenticated})
|
||
is in used; therefore user variables (see below) may be
|
||
a better choice to customize behavior based on the user
|
||
running @sc{cvs}.
|
||
@c Based on these limitations, should we deprecate ~?
|
||
@c What is it good for? Are people using it?
|
||
|
||
One may want to know about various pieces of
|
||
information internal to @sc{cvs}. A @sc{cvs} internal
|
||
variable has the syntax @code{$@{@var{variable}@}},
|
||
where @var{variable} starts with a letter and consists
|
||
of alphanumberic characters and @samp{_}. If the
|
||
character following @var{variable} is a
|
||
non-alphanumeric character other than @samp{_}, the
|
||
@samp{@{} and @samp{@}} can be omitted. The @sc{cvs}
|
||
internal variables are:
|
||
|
||
@table @code
|
||
@item CVSROOT
|
||
This is the value of the @sc{cvs} root in use.
|
||
@xref{Repository}, for a description of the various
|
||
ways to specify this.
|
||
|
||
@item RCSBIN
|
||
This is the value @sc{cvs} is using for where to find
|
||
@sc{rcs} binaries. @xref{Global options}, for a
|
||
description of how to specify this.
|
||
|
||
@item CVSEDITOR
|
||
@itemx VISUAL
|
||
@itemx EDITOR
|
||
These all expand to the same value, which is the editor
|
||
that @sc{cvs} is using. @xref{Global options}, for how
|
||
to specify this.
|
||
|
||
@item USER
|
||
Username of the user running @sc{cvs} (on the @sc{cvs}
|
||
server machine).
|
||
@end table
|
||
|
||
If you want to pass a value to the administrative files
|
||
which the user that is running @sc{cvs} can specify,
|
||
use a user variable. To expand a user variable, the
|
||
administrative file contains
|
||
@code{$@{=@var{variable}@}}. To set a user variable,
|
||
specify the global option @samp{-s} to @sc{cvs}, with
|
||
argument @code{@var{variable}=@var{value}}. It may be
|
||
particularly useful to specify this option via
|
||
@file{.cvsrc} (@pxref{~/.cvsrc}).
|
||
|
||
For example, if you want the administrative file to
|
||
refer to a test directory you might create a user
|
||
variable @code{TESTDIR}. Then if @sc{cvs} is invoked
|
||
as
|
||
|
||
@example
|
||
cvs -s TESTDIR=/work/local/tests
|
||
@end example
|
||
|
||
@noindent
|
||
and the
|
||
administrative file contains @code{sh
|
||
$@{=TESTDIR@}/runtests}, then that string is expanded
|
||
to @code{sh /work/local/tests/runtests}.
|
||
|
||
All other strings containing @samp{$} are reserved;
|
||
there is no way to quote a @samp{$} character so that
|
||
@samp{$} represents itself.
|
||
|
||
@c ---------------------------------------------------------------------
|
||
@node Environment variables
|
||
@appendix All environment variables which affect CVS
|
||
@cindex Environment variables
|
||
@cindex Reference manual for variables
|
||
|
||
This is a complete list of all environment variables
|
||
that affect @sc{cvs}.
|
||
|
||
@table @code
|
||
@cindex CVSIGNORE
|
||
@item $CVSIGNORE
|
||
A whitespace-separated list of file name patterns that
|
||
@sc{cvs} should ignore. @xref{cvsignore}.
|
||
|
||
@cindex CVSWRAPPERS
|
||
@item $CVSWRAPPERS
|
||
A whitespace-separated list of file name patterns that
|
||
@sc{cvs} should treat as wrappers. @xref{Wrappers}.
|
||
|
||
@cindex CVSREAD
|
||
@cindex read-only files, and CVSREAD
|
||
@item $CVSREAD
|
||
If this is set, @code{checkout} and @code{update} will
|
||
try hard to make the files in your working directory
|
||
read-only. When this is not set, the default behavior
|
||
is to permit modification of your working files.
|
||
|
||
@cindex CVSROOT
|
||
@item $CVSROOT
|
||
Should contain the full pathname to the root of the @sc{cvs}
|
||
source repository (where the @sc{rcs} history files are
|
||
kept). This information must be available to @sc{cvs} for
|
||
most commands to execute; if @code{$CVSROOT} is not set,
|
||
or if you wish to override it for one invocation, you
|
||
can supply it on the command line: @samp{cvs -d cvsroot
|
||
cvs_command@dots{}} Once you have checked out a working
|
||
directory, @sc{cvs} stores the appropriate root (in
|
||
the file @file{CVS/Root}), so normally you only need to
|
||
worry about this when initially checking out a working
|
||
directory.
|
||
|
||
@cindex EDITOR
|
||
@cindex CVSEDITOR
|
||
@item $EDITOR
|
||
@itemx $CVSEDITOR
|
||
Specifies the program to use for recording log messages
|
||
during commit. @code{$CVSEDITOR} overrides
|
||
@code{$EDITOR}. See @ref{Committing your changes}.
|
||
|
||
@cindex PATH
|
||
@item $PATH
|
||
If @code{$RCSBIN} is not set, and no path is compiled
|
||
into @sc{cvs}, it will use @code{$PATH} to try to find all
|
||
programs it uses.
|
||
|
||
@cindex RCSBIN
|
||
@item $RCSBIN
|
||
This is the value @sc{cvs} is using for where to find
|
||
@sc{rcs} binaries. @xref{Global options}, for a
|
||
description of how to specify this. If not set, a
|
||
compiled-in value is used, or your @code{$PATH} is searched.
|
||
|
||
@cindex HOME
|
||
@item $HOME
|
||
@cindex HOMEPATH
|
||
@item $HOMEPATH
|
||
Used to locate the directory where the @file{.cvsrc}
|
||
file is searched (@code{$HOMEPATH} is used for Windows-NT).
|
||
@pxref{~/.cvsrc}
|
||
|
||
@cindex CVS_RSH
|
||
@item $CVS_RSH
|
||
Specifies the external program which CVS connects with,
|
||
when @code{:ext:} access method is specified.
|
||
@pxref{Connecting via rsh}.
|
||
|
||
@item $CVS_SERVER
|
||
Used in client-server mode when accessing a remote
|
||
repository using @sc{rsh}. It specifies the name of
|
||
the program to start on the server side when accessing
|
||
a remote repository using @sc{rsh}. The default value
|
||
is @code{cvs}. @pxref{Connecting via rsh}
|
||
|
||
@item $CVS_PASSFILE
|
||
Used in client-server mode when accessing the @code{cvs
|
||
login server}. Default value is @file{$HOME/.cvspass}.
|
||
@pxref{Password authentication client}
|
||
|
||
@item $CVS_CLIENT_PORT
|
||
Used in client-server mode when accessing the server
|
||
via Kerberos.
|
||
@pxref{Kerberos authenticated}
|
||
|
||
@cindex CVS_RCMD_PORT
|
||
@item $CVS_RCMD_PORT
|
||
Used in client-server mode. If set, specifies the port
|
||
number to be used when accessing the @sc{rcmd} demon on
|
||
the server side. (Currently not used for Unix clients).
|
||
|
||
@cindex CVS_CLIENT_LOG
|
||
@item $CVS_CLIENT_LOG
|
||
Used for debugging only in client-server
|
||
mode. If set, everything send to the server is logged
|
||
into @file{@code{$CVS_CLIENT_LOG}.in} and everything
|
||
send from the server is logged into
|
||
@file{@code{$CVS_CLIENT_LOG}.out}.
|
||
|
||
@cindex CVS_SERVER_SLEEP
|
||
@item $CVS_SERVER_SLEEP
|
||
Used only for debugging the server side in
|
||
client-server mode. If set, delays the start of the
|
||
server child process the the specified amount of
|
||
seconds so that you can attach to it with a debugger.
|
||
|
||
@cindex CVS_IGNORE_REMOTE_ROOT
|
||
@item $CVS_IGNORE_REMOTE_ROOT
|
||
(What is the purpose of this variable?)
|
||
|
||
@cindex COMSPEC
|
||
@item $COMSPEC
|
||
Used under OS/2 only. It specifies the name of the
|
||
command interpreter and defaults to @sc{cmd.exe}.
|
||
|
||
@cindex TMPDIR
|
||
@item $TMPDIR
|
||
@cindex TMP
|
||
@itemx $TMP
|
||
@cindex TEMP
|
||
@itemx $TEMP
|
||
@cindex temporary files, location of
|
||
@c I'm not even sure I've documented all the
|
||
@c conventions here. Furthermore, those conventions are
|
||
@c pretty crazy and they should be simplified.
|
||
Directory in which temporary files are located. Those
|
||
parts of @sc{cvs} which are implemented using @sc{rcs}
|
||
inspect the above variables in the order they appear
|
||
above and the first value found is taken; if none of
|
||
them are set, a host-dependent default is used,
|
||
typically @file{/tmp}. The @sc{cvs} server uses
|
||
@code{TMPDIR}. @xref{Global options}, for a
|
||
description of how to specify this.
|
||
Some parts of @sc{cvs} will always use @file{/tmp} (via
|
||
the @code{tmpnam} function provided by the system).
|
||
|
||
On Windows NT, @code{TMP} is used (via the @code{_tempnam}
|
||
function provided by the system).
|
||
|
||
The @code{patch} program which is used by the @sc{cvs}
|
||
client uses @code{TMPDIR}, and if it is not set, uses
|
||
@file{/tmp} (at least with GNU patch 2.1).
|
||
@end table
|
||
|
||
@sc{cvs} invokes @sc{rcs} to perform certain
|
||
operations. The following environment
|
||
variables affect @sc{rcs}. Note that if you are using
|
||
the client/server @sc{cvs}, these variables need to be
|
||
set on the server side (which may or not may be
|
||
possible depending on how you are connecting). There
|
||
is probably not any need to set any of them, however.
|
||
|
||
@table @code
|
||
@cindex LOGNAME
|
||
@item $LOGNAME
|
||
@cindex USER
|
||
@itemx $USER
|
||
If set, they affect who @sc{rcs} thinks you are. If you
|
||
have trouble checking in files it might be because your
|
||
login name differs from the setting of e.g.
|
||
@code{$LOGNAME}.
|
||
|
||
@cindex RCSINIT
|
||
@item $RCSINIT
|
||
Options prepended to the argument list, separated by
|
||
spaces. A backslash escapes spaces within an option.
|
||
The @code{$RCSINIT} options are prepended to the
|
||
argument lists of most @sc{rcs} commands.
|
||
@end table
|
||
|
||
@c ---------------------------------------------------------------------
|
||
@node Troubleshooting
|
||
@appendix Troubleshooting
|
||
|
||
@menu
|
||
* Error messages:: Partial list of CVS errors
|
||
@end menu
|
||
|
||
@ignore
|
||
@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
|
||
@c @node Bad administrative files
|
||
@appendixsec Bad administrative files
|
||
|
||
@c -- Give hints on how to fix them
|
||
@end ignore
|
||
|
||
@node Error messages
|
||
@appendixsec Partial list of error messages
|
||
|
||
Here is a partial list of error messages that you may
|
||
see from @sc{cvs}. It is not a complete list---@sc{cvs}
|
||
is capable of printing many, many error messages, often
|
||
with parts of them supplied by the operating system,
|
||
but the intention is to list the common and/or
|
||
potentially confusing error messages.
|
||
|
||
The messages are alphabetical, but introductory text
|
||
such as @samp{cvs update: } is not considered in
|
||
ordering them.
|
||
|
||
In some cases the list includes messages printed by old
|
||
versions of @sc{cvs} (partly because users may not be
|
||
sure which version of @sc{cvs} they are using at any
|
||
particular moment).
|
||
|
||
@table @code
|
||
@c FIXME: What is the correct way to format a multiline
|
||
@c error message here? Maybe @table is the wrong
|
||
@c choice? Texinfo gurus?
|
||
@item cannot change permissions on temporary directory
|
||
@example
|
||
Operation not permitted
|
||
@end example
|
||
This message has been happening in a non-reproducible,
|
||
occasional way when we run the client/server testsuite,
|
||
both on Red Hat Linux 3.0.3 and 4.1. We haven't been
|
||
able to figure out what causes it, nor is it known
|
||
whether it is specific to linux (or even to this
|
||
particular machine!). If the problem does occur on
|
||
other unices, @samp{Operation not permitted} would be
|
||
likely to read @samp{Not owner} or whatever the system
|
||
in question uses for the unix @code{EPERM} error. If
|
||
you have any information to add, please let us know as
|
||
described in @ref{BUGS}. If you experience this error
|
||
while using @sc{cvs}, retrying the operation which
|
||
produced it should work fine.
|
||
@c Most recently this was in the multibranch-5 test.
|
||
@c But I'm not sure it is specific to that test.
|
||
|
||
@c For one example see basica-1a10 in the testsuite
|
||
@c For another example, "cvs co ." on NT; see comment
|
||
@c at windows-NT/filesubr.c (expand_wild).
|
||
@c For another example, "cvs co foo/bar" where foo exists.
|
||
@item cannot open CVS/Entries for reading: No such file or directory
|
||
This generally indicates a @sc{cvs} internal error, and
|
||
can be handled as with other @sc{cvs} bugs
|
||
(@pxref{BUGS}). Usually there is a workaround---the
|
||
exact nature of which would depend on the situation but
|
||
which hopefully could be figured out.
|
||
|
||
@item cvs [checkout aborted]: cannot rename file @var{file} to CVS/,,@var{file}: Invalid argument
|
||
This message has been reported as intermittently
|
||
happening with CVS 1.9 on Solaris 2.5. The cause is
|
||
unknown; if you know more about what causes it, let us
|
||
know as described in @ref{BUGS}.
|
||
|
||
@item cvs [update aborted]: could not patch @var{file}: No such file or directory
|
||
This means that there was a problem finding the
|
||
@code{patch} program. Make sure that it is in your
|
||
@code{PATH}. Note that despite appearances the message
|
||
is @emph{not} referring to whether it can find @var{file}.
|
||
@c Future versions of @sc{cvs} are
|
||
@c expected to dispense with the need for an external
|
||
@c patch program, but might as well not advertise
|
||
@c vaporware.
|
||
@c Even after that change is made, probably want to
|
||
@c preserve this message, see above about old messages.
|
||
|
||
@item cvs update: could not patch @var{file}; will refetch
|
||
This means that for whatever reason the client was
|
||
unable to apply a patch that the server sent. The
|
||
message is nothing to be concerned about, because
|
||
inability to apply the patch only slows things down and
|
||
has no effect on what @sc{cvs} does.
|
||
@c xref to update output. Or File status?
|
||
@c Or some place else that
|
||
@c explains this whole "patch"/P/Needs Patch thing?
|
||
|
||
@item dying gasps from @var{server} unexpected
|
||
This message seems to be caused by a hard-to-track-down
|
||
bug in @sc{cvs} or the systems it runs on (we don't
|
||
know---we haven't tracked it down yet!). If you see it,
|
||
you probably can just retry the operation which failed,
|
||
or if you have discovered information concerning its
|
||
cause, please let us know as described in @ref{BUGS}.
|
||
|
||
@item end of file from server (consult above messages if any)
|
||
The most common cause for this message is if you are
|
||
using an external @code{rsh} program and it exited with
|
||
an error. In this case the @code{rsh} program should
|
||
have printed a message, which will appear before the
|
||
above message. For more information on setting up a
|
||
@sc{cvs} client and server, see @ref{Remote repositories}.
|
||
|
||
@cindex mkmodules
|
||
@item cvs commit: Executing 'mkmodules'
|
||
This means that your repository is set up for a version
|
||
of @sc{cvs} prior to @sc{cvs} 1.8. When using @sc{cvs}
|
||
1.8 or later, the above message will be preceded by
|
||
|
||
@example
|
||
cvs commit: Rebuilding administrative file database
|
||
@end example
|
||
|
||
If you see both messages, the database is being rebuilt
|
||
twice, which is unnecessary but harmless. If you wish
|
||
to avoid the duplication, and you have no versions of
|
||
@sc{cvs} 1.7 or earlier in use, remove @code{-i mkmodules}
|
||
every place it appears in your @code{modules}
|
||
file. For more information on the @code{modules} file,
|
||
see @ref{modules}.
|
||
|
||
@item cvs [server aborted]: received broken pipe signal
|
||
This message seems to be caused by a hard-to-track-down
|
||
bug in @sc{cvs} or the systems it runs on (we don't
|
||
know---we haven't tracked it down yet!). It seems to
|
||
happen only after a @sc{cvs} command has completed, and
|
||
you should be able to just ignore the message.
|
||
However, if you have discovered information concerning its
|
||
cause, please let us know as described in @ref{BUGS}.
|
||
|
||
@item cvs commit: Up-to-date check failed for `@var{file}'
|
||
This means that someone else has committed a change to
|
||
that file since the last time that you did a @code{cvs
|
||
update}. So before proceeding with your @code{cvs
|
||
commit} you need to @code{cvs update}. CVS will merge
|
||
the changes that you made and the changes that the
|
||
other person made. If it does not detect any conflicts
|
||
it will report @samp{M cacErrCodes.h} and you are ready
|
||
to @code{cvs commit}. If it detects conflicts it will
|
||
print a message saying so, will report @samp{C cacErrCodes.h},
|
||
and you need to manually resolve the
|
||
conflict. For more details on this process see
|
||
@ref{Conflicts example}.
|
||
|
||
@item Usage: diff3 [-exEX3 [-i | -m] [-L label1 -L label3]] file1 file2 file3
|
||
@example
|
||
Only one of [exEX3] allowed
|
||
@end example
|
||
This indicates a problem with the installation of
|
||
@code{diff3} and @code{rcsmerge}. Specifically
|
||
@code{rcsmerge} was compiled to look for GNU diff3, but
|
||
it is finding unix diff3 instead. The exact text of
|
||
the message will vary depending on the system. The
|
||
solution is to make sure @code{rcsmerge} finds GNU
|
||
diff3. Depending on how @code{rcsmerge} was compiled,
|
||
it might be sufficient to place GNU diff3 in your
|
||
@code{PATH}, or it might be necessary to recompile
|
||
@code{rcsmerge} or find a binary distribution of
|
||
@code{rcsmerge} which looks in the @code{PATH}.
|
||
@c Should we mention the cvsaux binaries here?
|
||
|
||
@item cvs commit: warning: editor session failed
|
||
@cindex exit status, of editor
|
||
This means that the editor which @sc{cvs} is using exits with a nonzero
|
||
exit status. Some versions of vi will do this even when there was not
|
||
a problem editing the file. If so, point the
|
||
@sc{CVSEDITOR} environment variable to a small script
|
||
such as:
|
||
|
||
@example
|
||
#!/bin/sh
|
||
vi $*
|
||
exit 0
|
||
@end example
|
||
|
||
@c "warning: foo was lost" and "no longer pertinent" (both normal).
|
||
@c Would be nice to write these up--they are
|
||
@c potentially confusing for the new user.
|
||
@end table
|
||
|
||
@c ---------------------------------------------------------------------
|
||
@node Copying
|
||
@appendix GNU GENERAL PUBLIC LICENSE
|
||
@center Version 2, June 1991
|
||
|
||
@display
|
||
Copyright @copyright{} 1989, 1991 Free Software Foundation, Inc.
|
||
59 Temple Place - Suite 330, Boston, MA 02111-1307, USA
|
||
|
||
Everyone is permitted to copy and distribute verbatim copies
|
||
of this license document, but changing it is not allowed.
|
||
@end display
|
||
|
||
@unnumberedsec Preamble
|
||
|
||
The licenses for most software are designed to take away your
|
||
freedom to share and change it. By contrast, the GNU General Public
|
||
License is intended to guarantee your freedom to share and change free
|
||
software---to make sure the software is free for all its users. This
|
||
General Public License applies to most of the Free Software
|
||
Foundation's software and to any other program whose authors commit to
|
||
using it. (Some other Free Software Foundation software is covered by
|
||
the GNU Library General Public License instead.) You can apply it to
|
||
your programs, too.
|
||
|
||
When we speak of free software, we are referring to freedom, not
|
||
price. Our General Public Licenses are designed to make sure that you
|
||
have the freedom to distribute copies of free software (and charge for
|
||
this service if you wish), that you receive source code or can get it
|
||
if you want it, that you can change the software or use pieces of it
|
||
in new free programs; and that you know you can do these things.
|
||
|
||
To protect your rights, we need to make restrictions that forbid
|
||
anyone to deny you these rights or to ask you to surrender the rights.
|
||
These restrictions translate to certain responsibilities for you if you
|
||
distribute copies of the software, or if you modify it.
|
||
|
||
For example, if you distribute copies of such a program, whether
|
||
gratis or for a fee, you must give the recipients all the rights that
|
||
you have. You must make sure that they, too, receive or can get the
|
||
source code. And you must show them these terms so they know their
|
||
rights.
|
||
|
||
We protect your rights with two steps: (1) copyright the software, and
|
||
(2) offer you this license which gives you legal permission to copy,
|
||
distribute and/or modify the software.
|
||
|
||
Also, for each author's protection and ours, we want to make certain
|
||
that everyone understands that there is no warranty for this free
|
||
software. If the software is modified by someone else and passed on, we
|
||
want its recipients to know that what they have is not the original, so
|
||
that any problems introduced by others will not reflect on the original
|
||
authors' reputations.
|
||
|
||
Finally, any free program is threatened constantly by software
|
||
patents. We wish to avoid the danger that redistributors of a free
|
||
program will individually obtain patent licenses, in effect making the
|
||
program proprietary. To prevent this, we have made it clear that any
|
||
patent must be licensed for everyone's free use or not licensed at all.
|
||
|
||
The precise terms and conditions for copying, distribution and
|
||
modification follow.
|
||
|
||
@iftex
|
||
@heading TERMS AND CONDITIONS FOR COPYING,
|
||
@heading DISTRIBUTION AND MODIFICATION
|
||
@end iftex
|
||
@ifinfo
|
||
@center TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION
|
||
@end ifinfo
|
||
|
||
@enumerate 0
|
||
@item
|
||
This License applies to any program or other work which contains
|
||
a notice placed by the copyright holder saying it may be distributed
|
||
under the terms of this General Public License. The ``Program'', below,
|
||
refers to any such program or work, and a ``work based on the Program''
|
||
means either the Program or any derivative work under copyright law:
|
||
that is to say, a work containing the Program or a portion of it,
|
||
either verbatim or with modifications and/or translated into another
|
||
language. (Hereinafter, translation is included without limitation in
|
||
the term ``modification''.) Each licensee is addressed as ``you''.
|
||
|
||
Activities other than copying, distribution and modification are not
|
||
covered by this License; they are outside its scope. The act of
|
||
running the Program is not restricted, and the output from the Program
|
||
is covered only if its contents constitute a work based on the
|
||
Program (independent of having been made by running the Program).
|
||
Whether that is true depends on what the Program does.
|
||
|
||
@item
|
||
You may copy and distribute verbatim copies of the Program's
|
||
source code as you receive it, in any medium, provided that you
|
||
conspicuously and appropriately publish on each copy an appropriate
|
||
copyright notice and disclaimer of warranty; keep intact all the
|
||
notices that refer to this License and to the absence of any warranty;
|
||
and give any other recipients of the Program a copy of this License
|
||
along with the Program.
|
||
|
||
You may charge a fee for the physical act of transferring a copy, and
|
||
you may at your option offer warranty protection in exchange for a fee.
|
||
|
||
@item
|
||
You may modify your copy or copies of the Program or any portion
|
||
of it, thus forming a work based on the Program, and copy and
|
||
distribute such modifications or work under the terms of Section 1
|
||
above, provided that you also meet all of these conditions:
|
||
|
||
@enumerate a
|
||
@item
|
||
You must cause the modified files to carry prominent notices
|
||
stating that you changed the files and the date of any change.
|
||
|
||
@item
|
||
You must cause any work that you distribute or publish, that in
|
||
whole or in part contains or is derived from the Program or any
|
||
part thereof, to be licensed as a whole at no charge to all third
|
||
parties under the terms of this License.
|
||
|
||
@item
|
||
If the modified program normally reads commands interactively
|
||
when run, you must cause it, when started running for such
|
||
interactive use in the most ordinary way, to print or display an
|
||
announcement including an appropriate copyright notice and a
|
||
notice that there is no warranty (or else, saying that you provide
|
||
a warranty) and that users may redistribute the program under
|
||
these conditions, and telling the user how to view a copy of this
|
||
License. (Exception: if the Program itself is interactive but
|
||
does not normally print such an announcement, your work based on
|
||
the Program is not required to print an announcement.)
|
||
@end enumerate
|
||
|
||
These requirements apply to the modified work as a whole. If
|
||
identifiable sections of that work are not derived from the Program,
|
||
and can be reasonably considered independent and separate works in
|
||
themselves, then this License, and its terms, do not apply to those
|
||
sections when you distribute them as separate works. But when you
|
||
distribute the same sections as part of a whole which is a work based
|
||
on the Program, the distribution of the whole must be on the terms of
|
||
this License, whose permissions for other licensees extend to the
|
||
entire whole, and thus to each and every part regardless of who wrote it.
|
||
|
||
Thus, it is not the intent of this section to claim rights or contest
|
||
your rights to work written entirely by you; rather, the intent is to
|
||
exercise the right to control the distribution of derivative or
|
||
collective works based on the Program.
|
||
|
||
In addition, mere aggregation of another work not based on the Program
|
||
with the Program (or with a work based on the Program) on a volume of
|
||
a storage or distribution medium does not bring the other work under
|
||
the scope of this License.
|
||
|
||
@item
|
||
You may copy and distribute the Program (or a work based on it,
|
||
under Section 2) in object code or executable form under the terms of
|
||
Sections 1 and 2 above provided that you also do one of the following:
|
||
|
||
@enumerate a
|
||
@item
|
||
Accompany it with the complete corresponding machine-readable
|
||
source code, which must be distributed under the terms of Sections
|
||
1 and 2 above on a medium customarily used for software interchange; or,
|
||
|
||
@item
|
||
Accompany it with a written offer, valid for at least three
|
||
years, to give any third party, for a charge no more than your
|
||
cost of physically performing source distribution, a complete
|
||
machine-readable copy of the corresponding source code, to be
|
||
distributed under the terms of Sections 1 and 2 above on a medium
|
||
customarily used for software interchange; or,
|
||
|
||
@item
|
||
Accompany it with the information you received as to the offer
|
||
to distribute corresponding source code. (This alternative is
|
||
allowed only for noncommercial distribution and only if you
|
||
received the program in object code or executable form with such
|
||
an offer, in accord with Subsection b above.)
|
||
@end enumerate
|
||
|
||
The source code for a work means the preferred form of the work for
|
||
making modifications to it. For an executable work, complete source
|
||
code means all the source code for all modules it contains, plus any
|
||
associated interface definition files, plus the scripts used to
|
||
control compilation and installation of the executable. However, as a
|
||
special exception, the source code distributed need not include
|
||
anything that is normally distributed (in either source or binary
|
||
form) with the major components (compiler, kernel, and so on) of the
|
||
operating system on which the executable runs, unless that component
|
||
itself accompanies the executable.
|
||
|
||
If distribution of executable or object code is made by offering
|
||
access to copy from a designated place, then offering equivalent
|
||
access to copy the source code from the same place counts as
|
||
distribution of the source code, even though third parties are not
|
||
compelled to copy the source along with the object code.
|
||
|
||
@item
|
||
You may not copy, modify, sublicense, or distribute the Program
|
||
except as expressly provided under this License. Any attempt
|
||
otherwise to copy, modify, sublicense or distribute the Program is
|
||
void, and will automatically terminate your rights under this License.
|
||
However, parties who have received copies, or rights, from you under
|
||
this License will not have their licenses terminated so long as such
|
||
parties remain in full compliance.
|
||
|
||
@item
|
||
You are not required to accept this License, since you have not
|
||
signed it. However, nothing else grants you permission to modify or
|
||
distribute the Program or its derivative works. These actions are
|
||
prohibited by law if you do not accept this License. Therefore, by
|
||
modifying or distributing the Program (or any work based on the
|
||
Program), you indicate your acceptance of this License to do so, and
|
||
all its terms and conditions for copying, distributing or modifying
|
||
the Program or works based on it.
|
||
|
||
@item
|
||
Each time you redistribute the Program (or any work based on the
|
||
Program), the recipient automatically receives a license from the
|
||
original licensor to copy, distribute or modify the Program subject to
|
||
these terms and conditions. You may not impose any further
|
||
restrictions on the recipients' exercise of the rights granted herein.
|
||
You are not responsible for enforcing compliance by third parties to
|
||
this License.
|
||
|
||
@item
|
||
If, as a consequence of a court judgment or allegation of patent
|
||
infringement or for any other reason (not limited to patent issues),
|
||
conditions are imposed on you (whether by court order, agreement or
|
||
otherwise) that contradict the conditions of this License, they do not
|
||
excuse you from the conditions of this License. If you cannot
|
||
distribute so as to satisfy simultaneously your obligations under this
|
||
License and any other pertinent obligations, then as a consequence you
|
||
may not distribute the Program at all. For example, if a patent
|
||
license would not permit royalty-free redistribution of the Program by
|
||
all those who receive copies directly or indirectly through you, then
|
||
the only way you could satisfy both it and this License would be to
|
||
refrain entirely from distribution of the Program.
|
||
|
||
If any portion of this section is held invalid or unenforceable under
|
||
any particular circumstance, the balance of the section is intended to
|
||
apply and the section as a whole is intended to apply in other
|
||
circumstances.
|
||
|
||
It is not the purpose of this section to induce you to infringe any
|
||
patents or other property right claims or to contest validity of any
|
||
such claims; this section has the sole purpose of protecting the
|
||
integrity of the free software distribution system, which is
|
||
implemented by public license practices. Many people have made
|
||
generous contributions to the wide range of software distributed
|
||
through that system in reliance on consistent application of that
|
||
system; it is up to the author/donor to decide if he or she is willing
|
||
to distribute software through any other system and a licensee cannot
|
||
impose that choice.
|
||
|
||
This section is intended to make thoroughly clear what is believed to
|
||
be a consequence of the rest of this License.
|
||
|
||
@item
|
||
If the distribution and/or use of the Program is restricted in
|
||
certain countries either by patents or by copyrighted interfaces, the
|
||
original copyright holder who places the Program under this License
|
||
may add an explicit geographical distribution limitation excluding
|
||
those countries, so that distribution is permitted only in or among
|
||
countries not thus excluded. In such case, this License incorporates
|
||
the limitation as if written in the body of this License.
|
||
|
||
@item
|
||
The Free Software Foundation may publish revised and/or new versions
|
||
of the General Public License from time to time. Such new versions will
|
||
be similar in spirit to the present version, but may differ in detail to
|
||
address new problems or concerns.
|
||
|
||
Each version is given a distinguishing version number. If the Program
|
||
specifies a version number of this License which applies to it and ``any
|
||
later version'', you have the option of following the terms and conditions
|
||
either of that version or of any later version published by the Free
|
||
Software Foundation. If the Program does not specify a version number of
|
||
this License, you may choose any version ever published by the Free Software
|
||
Foundation.
|
||
|
||
@item
|
||
If you wish to incorporate parts of the Program into other free
|
||
programs whose distribution conditions are different, write to the author
|
||
to ask for permission. For software which is copyrighted by the Free
|
||
Software Foundation, write to the Free Software Foundation; we sometimes
|
||
make exceptions for this. Our decision will be guided by the two goals
|
||
of preserving the free status of all derivatives of our free software and
|
||
of promoting the sharing and reuse of software generally.
|
||
|
||
@iftex
|
||
@heading NO WARRANTY
|
||
@end iftex
|
||
@ifinfo
|
||
@center NO WARRANTY
|
||
@end ifinfo
|
||
|
||
@item
|
||
BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY
|
||
FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN
|
||
OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES
|
||
PROVIDE THE PROGRAM ``AS IS'' WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED
|
||
OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
|
||
MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS
|
||
TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD THE
|
||
PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING,
|
||
REPAIR OR CORRECTION.
|
||
|
||
@item
|
||
IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
|
||
WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR
|
||
REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES,
|
||
INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING
|
||
OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED
|
||
TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY
|
||
YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER
|
||
PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE
|
||
POSSIBILITY OF SUCH DAMAGES.
|
||
@end enumerate
|
||
|
||
@iftex
|
||
@heading END OF TERMS AND CONDITIONS
|
||
@end iftex
|
||
@ifinfo
|
||
@center END OF TERMS AND CONDITIONS
|
||
@end ifinfo
|
||
|
||
@page
|
||
@unnumberedsec How to Apply These Terms to Your New Programs
|
||
|
||
If you develop a new program, and you want it to be of the greatest
|
||
possible use to the public, the best way to achieve this is to make it
|
||
free software which everyone can redistribute and change under these terms.
|
||
|
||
To do so, attach the following notices to the program. It is safest
|
||
to attach them to the start of each source file to most effectively
|
||
convey the exclusion of warranty; and each file should have at least
|
||
the ``copyright'' line and a pointer to where the full notice is found.
|
||
|
||
@smallexample
|
||
@var{one line to give the program's name and a brief idea of what it does.}
|
||
Copyright (C) 19@var{yy} @var{name of author}
|
||
|
||
This program is free software; you can redistribute it and/or modify
|
||
it under the terms of the GNU General Public License as published by
|
||
the Free Software Foundation; either version 2 of the License, or
|
||
(at your option) any later version.
|
||
|
||
This program is distributed in the hope that it will be useful,
|
||
but WITHOUT ANY WARRANTY; without even the implied warranty of
|
||
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
|
||
GNU General Public License for more details.
|
||
|
||
You should have received a copy of the GNU General Public License
|
||
along with this program; if not, write to the Free Software
|
||
Foundation, Inc., 59 Temple Place - Suite 330,
|
||
Boston, MA 02111-1307, USA.
|
||
@end smallexample
|
||
|
||
Also add information on how to contact you by electronic and paper mail.
|
||
|
||
If the program is interactive, make it output a short notice like this
|
||
when it starts in an interactive mode:
|
||
|
||
@smallexample
|
||
Gnomovision version 69, Copyright (C) 19@var{yy} @var{name of author}
|
||
Gnomovision comes with ABSOLUTELY NO WARRANTY; for details
|
||
type `show w'.
|
||
This is free software, and you are welcome to redistribute it
|
||
under certain conditions; type `show c' for details.
|
||
@end smallexample
|
||
|
||
The hypothetical commands @samp{show w} and @samp{show c} should show
|
||
the appropriate parts of the General Public License. Of course, the
|
||
commands you use may be called something other than @samp{show w} and
|
||
@samp{show c}; they could even be mouse-clicks or menu items---whatever
|
||
suits your program.
|
||
|
||
You should also get your employer (if you work as a programmer) or your
|
||
school, if any, to sign a ``copyright disclaimer'' for the program, if
|
||
necessary. Here is a sample; alter the names:
|
||
|
||
@smallexample
|
||
Yoyodyne, Inc., hereby disclaims all copyright interest in the program
|
||
`Gnomovision' (which makes passes at compilers) written by James Hacker.
|
||
|
||
@var{signature of Ty Coon}, 1 April 1989
|
||
Ty Coon, President of Vice
|
||
@end smallexample
|
||
|
||
This General Public License does not permit incorporating your program into
|
||
proprietary programs. If your program is a subroutine library, you may
|
||
consider it more useful to permit linking proprietary applications with the
|
||
library. If this is what you want to do, use the GNU Library General
|
||
Public License instead of this License.
|
||
|
||
@c ---------------------------------------------------------------------
|
||
@node Index
|
||
@unnumbered Index
|
||
@cindex Index
|
||
|
||
@printindex cp
|
||
|
||
@summarycontents
|
||
|
||
@contents
|
||
|
||
@bye
|
||
|
||
Local Variables:
|
||
fill-column: 55
|
||
End:
|