path: root/gnu/usr.bin/cvs/FAQ

Archive-name: cvs-faq
Hand Revision: 3.5		<<== Include this in your comments
Last Updated: 1995/03/09
$Revision: 1.4 $
$Date: 1995/10/02 23:13:07 $

===========================================================================
== Frequently Asked Questions about CVS (The Concurrent Versions System) ==
===========================================================================

    This document attempts to answer questions posed by users of CVS.

    CVS installers, administrators and maintainers looking for info on
    system setup should read the section entitled "Installing CVS".


    Disclaimer:

	Although an attempt has been made to ensure the veracity of the
	following material, no responsibility is assumed for any use, or
	for any consequences resulting from any use, of the information
	contained herein.  No guarantee of suitability for any purpose
	is offered or implied.	Nothing in this document may be assumed
	to represent the employers of its contributors.

	I also might have slipped in a whopper or two to see if you are
	paying attention.  ;-)	In other words, don't bet the house on
	anything you read here unless you have checked it out yourself.



    Send questions and answers (along with additions to, subtractions
    from, and divisions of existing questions -- no multiplications,
    square roots, or transcendental functions, my cabinet is full of them)
    to the author, who wrote all unattributed text: (Does it always
    feel strange to refer to oneself in the third person?)

		David G. Grubbs <dgg@world.std.com>


    Major revisions contain enough alterations to render change markers
    meaningless.  (Major revisions are those with a final digit of '0',
    such as 2.0 or 3.0.)  To help readers of previous versions of this
    document, minor revisions will be annotated:

    Change markers:  Column 1 will contain a:

	'-'	for a Question that has changed.
	'='	for an Answer that has changed.
	'#'	for an entry with changes to both Question and Answer.
	'+'	for a newly added Question and Answer.


    Trivial changes, such as question reordering or spelling and grammar
    corrections are not marked.	 Deleted questions will simply disappear,
    as will any question that can be answered by "get the latest release".

    Editorial comments are delimited by pairs of "[[" & "]]".  They
    contain either references to the (usually unfinished) nature of the
    FAQ entry itself, version-specific comments to be removed (or
    altered) when new revisions of CVS are released or snide remarks from
    the editor.

    If you plan to do anything with this document other than:

	- Read it.
	- Redistribute the whole document along with the date and revision.
	- Post sections as answers to CVS questions (as long as you
	  identify it as coming from the FAQ.)

    talk to the author first.



============================================
==  Section 0	====	Introduction	====
============================================

The questions in this document come from many sources in many forms.  Some
are simple, some verbose.  A few are difficult, but all of them have been
asked of the author at one time or another.  Some questions are really
three or more different problems rolled into one plaintive cry for help.
Others reveal one of the bugs or weaknesses of CVS.

CVS addresses some difficult problems to which there are no perfect
solutions.  CVS also changes over time as new features are required.

Therefore, the questions are about a complicated moving target.

Though in most cases I've tried to provide the simplest answer I can
think of, some of the *questions* are difficult to follow.  If you
aren't using CVS regularly, don't expect to understand everything.

A Frequently Asked Questions document is not a substitute for the man page
or any other documentation.  It is an attempt to answer questions.

You should also keep in mind that FAQs are not really intended to be
read in their entirety like a text book.  You should use "grep" or
your editor's search capability to hunt for keywords and read the
sections you need.


Questions are divided into five numbered Sections.  Sections are divided
into lettered sub-sections.  The questions are numbered sequentially
within each sub-section, though they are in no particular order.


	1. What is CVS?
	   A. What is CVS?  What's it for?  Why CVS?
	   B. Where do I find it?  Where can I find Help?
	   C. How does CVS differ from other similar software?
	   D. What do you mean by .  .	.? (Definitions)

	2. User Tasks
	   A. Getting Started
	   B. Common User Tasks
	   C. Less Common User Tasks
	   D. General Questions

	3. Commands
	   A. through P.  One section for each CVS command.

	4. Advanced Topics
	   A. Installing CVS
	   B. Setting up and Managing the Repository
	   C. Branching and Merging
	   D. Tricks of the Trade
	   E. Internal errors
	   F. Related Software
	   G. Engineering
	   H. Other Systems

	5. Past & Future
	   A. Contributors.
	   B. Bugs and Patches
	   C. Development
	   D. Professional Support

	6. Table of Contents


Final note:

	Except for the "Past & Future" section, all answers in this
	document refer to CVS version 1.4.  The latest released version is
	1.5.


============================================
==  Section 1	====	What is CVS?	====
============================================

----------------
-- Section 1A --	What is CVS?  What's it for?  Why CVS?
----------------

 **** Questions:

 1A.1	What does CVS stand for?  Can you describe it in one sentence?
 1A.2	What is CVS for?  What does it do for me?
 1A.3	How does CVS work?
 1A.4	What is CVS useful for?
 1A.5	What is CVS *not* useful for?


 **** Answers:

 1A.1	What does CVS stand for?  Can you describe it in one sentence?

	"CVS" is an acronym for the "Concurrent Versions System".

	CVS is a "Source Control" or "Revision Control" tool
	designed to keep track of source changes made by groups of
	developers working on the same files, allowing them to
	stay in sync with each other as each individual chooses.


 1A.2	What is CVS for?  What does it do for me?

	CVS is used to keep track of collections of files in a shared
	directory called "The Repository".  Each collection of files
	can be given a "module" name, which is used to "checkout"
	that collection.

	After checkout, files can be modified (using your favorite
	editor), "committed" back into the Repository and compared
	against earlier revisions.  Collections of files can be
	"tagged" with a symbolic name for later retrieval.

	You can add new files, remove files you no longer want, ask for
	information about sets of files in three different ways,
	produce patch "diffs" from a base revision and merge the
	committed changes of other developers into your working files.


 1A.3	How does CVS work?

	CVS saves its version-control information in RCS files stored in a
	directory hierarchy, called the Repository, which is separate from
	the user's working directory.

	Files in the Repository are stored in a format dictated by the
	RCS commands CVS uses to do much of its real work.  RCS files
	are standard byte-stream files with an internal format described
	by keywords stored in the files themselves.

	To begin work, you execute a "checkout" command, handing it a
	module name or directory path (relative to the $CVSROOT variable)
	you want to work on.  CVS copies the latest revision of each file
	in the specified module or directory out of the Repository and
	into a directory tree created in your current directory.  You may
	specify a particular branch to work on by symbolic name if you
	don't want to work on the default (main or trunk) branch.

	You may then modify files in the new directory tree, build them
	into output files and test the results.	 When you want to make
	your changes available to other developers, you "commit" them back
	into the Repository.

	Other developers can check out the same files at the same time.
	To merge the committed work of others into your working files
	you use the "update" command.  When your merged files build
	and test correctly, you may commit the merged result.  This
	method is referred to as "copy-modify-merge", which does not
	require locks on the source files.

	At any time, usually at some milestone, you can "tag" the
	committed files, producing a symbolic name that can be handed to a
	future "checkout" command.  A special form of "tag" produces a
	branch in development, as usually happens at "release" time.

	When you no longer plan to modify or refer to your local copy
	of the files, they can be removed.


 1A.4	What is CVS useful for?

	CVS is intended to handle source control for files in three major
	situations:

	1. Multiple developers working on the same files.

	   The major advantage of using CVS over the simpler tools like
	   RCS or SCCS is that it allows multiple developers to work on
	   the same sources at the same time.

	   The shared Repository provides a rendezvous for committed
	   sources that allows developers a fair amount of flexibility in
	   how often to publish (via the "commit" command) changes or
	   include work committed by others (via the "update" command).


	2. Tracking a stream of releases from a source vendor.

	   If you are making changes to sources distributed by someone
	   else, the CVS feature, called the Vendor Branch, allows you to
	   combine local modifications with repeated vendor releases.

	   I have found this most useful when dealing with sources from
	   three major classes of source vendor:

		a. Large companies who send you tapes full of the latest
		   release (e.g. Unix OS vendors, database companies).

		b. Public Domain software which *always* requires work.

		c. Pseudo-Public sources which may require work.
		   (e.g. GNU programs, X, CVS itself, etc.)


	3. Branching development.

	   Aside from the "Vendor Branch", there are three kinds of
	   "branches in development" that CVS can support:

	   a. Your working directory can be treated as a private branch.

	   b. A Development branch can be shared by one or more developers.

	   c. At release time, a branch is usually created for bug fixes.

	   (See 1D.9 and Section 4C for more info on branches.)

	   CVS's branch support is a bit primitive, but it was designed to
	   allow you to create branches, work on them for while and merge
	   them back into the main line of development.	 You should also
	   be able to merge work performed on the main branch into the
	   branch you are working on.  Arbitrary sharing and merging
	   between branches is not currently supported.


 1A.5	What is CVS *not* useful for?

	CVS is not a build system.

	    Though the structure of your Repository and modules file
	    interact with your build system (e.g. a tree of Makefiles),
	    they are essentially independent.

	    CVS does not dictate how you build anything.  It merely stores
	    files for retrieval in a tree structure you devise.

	    CVS does not dictate how to use disk space in the checked out
	    working directories.  If you require your Makefiles or build
	    procedures to know the relative positions of everything else,
	    you wind up requiring the entire Repository to be checked out.
	    That's simply bad planning.

	    If you modularize your work, and construct a build system
	    that will share files (via links, mounts, VPATH in Makefiles,
	    etc.), you can arrange your disk usage however you like.

	    But you have to remember that *any* such system is a lot of
	    work to construct and maintain.  CVS does not address the
	    issues involved.  You must use your brain and a collection
	    of other tools to provide a build scheme to match your plans.

	    Of course, you should use CVS to maintain the tools created to
	    support such a build system (scripts, Makefiles, etc).


	CVS is not a substitute for management.

	    You and your project leaders are expected to plan what you are
	    doing.  Everyone involved must be aware of schedules, merge
	    points, branch names, release dates and the range of
	    procedures needed to build products.  (If you produce it and
	    someone else uses it, it is a product.)  CVS can't cover for a
	    failure to manage your project.

	    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.


	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.

	    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 "conflict" is
	    purely textual, arising when two changes to the same base file
	    are near enough to spook the merge command into dropping
	    conflict markers into the merged file.

	    CVS is not capable of figuring out distributed conflicts in
	    program logic.  For example, if you change the arguments to
	    function X defined in file A and, at the same time, edit file
	    B, adding new calls to function X using the old arguments.
	    You are outside the realm of CVS's competence.

	    Acquire the habit of reading specs and talking to your peers.


	CVS is not a configuration management system.

	    CVS is a source control system.  The phrase "configuration
	    management" is a marketing term, not an industry-recognized
	    set of functions.

	    A true "configuration management system" would contain
	    elements of the following:

		* Source control.
		* Dependency tracking.
		* Build systems (i.e. What to build and how to find
		  things during a build.  What is shared?  What is local?)
		* Bug tracking.
		* Automated Testing procedures.
		* Release Engineering documentation and procedures.
		* Tape Construction.
		* Customer Installation.
		* A way for users to run different versions of the same
		  software on the same host at the same time.

	    CVS provides only the first.



----------------
-- Section 1B --	Where do I find CVS?  Where can I find Help?
----------------

 **** Questions:

 1B.1	How do I get more information about CVS?
 1B.2	Is there an archive of CVS material?
 1B.3	How do I get files out of the archive if I don't have FTP?
 1B.4	How do I get a copy of the latest version of CVS?
 1B.5	Is there a mailing list devoted to CVS?	 How do I find it?
 1B.6	What happened to the CVS Usenet newsgroup I heard about?


 **** Answers:

 1B.1	How do I get more information about CVS?

	1. The first thing I would do is to read the Info file that comes
	   with the CVS sources under "doc".  You can format and read the
	   cvs.texinfo file in two ways: 1. Use TeX to format it and a
	   "dvips" command to print it and 2. Install the cvs.info files
	   that are created by the Makefile and read them online using the
	   Emacs "info-mode" or a stand-alone "info" reader.

	2. Then I'd run "cvsinit" to set up a Repository and read the man
	   page while trying out the commands.

	   Type "cvs -H" for general help or "cvs -H command" for
	   command-specific help.

	3. For background, you can read the original CVS paper (in the
	   source tree, under "doc").  It describes the purpose of CVS and
	   some of how it was designed.	 Note that the emphasis of the
	   document (especially on multiple vendors providing the same
	   sources) is somewhat out of date.

	4. For more detailed information about "internals", read the man
	   pages for RCS.  If you are a programmer, you can also read the
	   source code to CVS.

	5. Other information and tutorials may be available in the "doc"
	   directory of the FTP archive described below.

	6. For current information, and a fair amount of detail, join the
	   info-cvs mailing list described below.


 1B.2	Is there an archive of CVS material?

	An anonymous FTP area has been set up.	It contains many of the
	CVS files you might want, including extra documentation, patches
	and a copy of the latest release.

		ftp ftp.delos.com
		>>> User:	anonymous
		>>> Passwd:	<Your Internet address>
		cd /pub/cvs
		get README
		get Index

	The README has more (and more up-to-date) information.	The Index
	contains a terse list of what is in the archive.

	A WWW home page is also available at http://www.delos.com/cvs.


 1B.3	How do I get files out of the archive if I don't have FTP?

	Use one of the FTP<->Email servers.  These are the ones
	I've been told about:


	1. FTPMAIL service is available from the same host as the FTP
	   server described above.  Send mail to "ftpmail@delos.com"
	   containing "help" in the body of the message.  For example,
	   on most Unix systems, you can type:

		echo help | Mail ftpmail@delos.com

	   The FTPMAIL server will respond with a document describing how
	   to use the server.  If the "Mail" command doesn't exist on your
	   system, try "mailx", "/usr/ucb/mail" or "/bin/mail".


	2. If you are on BITNET, use Princeton's BITFTP server.	 Type

		echo 'send help' | Mail bitftp@pucc.princeton.edu

	   (It is likely that only BITNET addresses can use this one.)


	3. Other possibilities I've heard of from the net:
	   (Try the one closest to you.)

		ftpmail@decwrl.dec.com
		ftpmail@sunsite.unc.edu
		ftpmail@cs.arizona.edu
		ftpmail@cs.uow.edu.au
		ftpmail@doc.ic.ac.uk


 1B.4	How do I get a copy of the latest version of CVS?

	The latest released version of CVS and all the programs it
	depends on should be available through anonymous FTP on any FSF
	archive.  The main FSF archive is at "prep.ai.mit.edu".	 There are
	mirrors of the FSF archive on UUNET and other large Internet sites.

		Program(s)	Suggested revision
		-----------	-----------------------
		CVS		1.5
		RCS		5.7 (latest version available today)
		GNU diff	2.7 (or later) [contained in diffutils-2.7]
		GDBM		1.5 (or later) [optional]

	The GNU version of diff is suggested by both the RCS and CVS
	configuration instructions because it works better than the
	standard version.

	It is a good idea not to accept the versions of CVS, RCS or diff
	you find lying on your system unless you have checked out their
	provenance.  Using inconsistent collections of tools can cause you
	more trouble than you can probably afford.

	The FTP archive mentioned above should contain the latest official
	release of CVS, some official and unofficial patches and possibly
	complete patched versions of CVS in use somewhere.


 1B.5	Is there a mailing list devoted to CVS?	 How do I find it?

	An Internet mailing list named "info-cvs" grew out of the private
	mailing list used by the CVS 1.3 alpha testers in early 1992.
	Throughout 1994, the list received an average of 100 messages per
	month.

	You can add yourself to the mailing list by sending an Email
	message to:

		info-cvs-request@prep.ai.mit.edu

	(Don't forget the "-request" or you'll send a message to the
	 whole list, some of whom are capable of remote execution.)

	Mail to the whole list should be sent to:

		info-cvs@prep.ai.mit.edu

	An archive of the mailing list is maintained in the FTP archive
	mentioned above.


 1B.6	What happened to the CVS Usenet newsgroup I heard about?


	A Usenet newsgroup named "gnu.cvs.info" was announced in April
	1993, with an expected creation date of August, 1993.

	As of this writing (October, 1994) it hasn't appeared.

	If the newsgroup is ever created, it and the mailing list should
	be bidirectionally gatewayed, meaning that you only need access to
	one of them.  Anything sent to the mailing list would be
	automatically posted to "gnu.cvs.info" and anything posted to the
	newsgroup would be automatically mailed to "info-cvs".

	A newsgroup would be easier to use than a mailing list.	 If the
	CVS newsgroup ever shows up, ask your system administrator whether
	you get the "gnu" hierarchy.  If so, select a news reader and dive
	in.


----------------
-- Section 1C --	How does CVS differ from other, similar software?
----------------

This section attempts to list programs purporting to cover some of the
same territory as CVS.	[[These are very sparsely documented here.  If you
know something about one of these tools, how about trying to flesh out an
entry or two?]]


 **** Questions:

 1C.1	How does CVS differ from RCS?
 1C.2	How does CVS differ from SCCS?
 1C.3	How does CVS differ from ClearCase?
#1C.4	How does CVS differ from TeamWare/SparcWorks?
 1C.5	How does CVS differ from Aegis?
 1C.6	How does CVS differ from Shapetools?
 1C.7	How does CVS differ from TeamNet?
 1C.8	How does CVS differ from ProFrame?
 1C.9	How does CVS differ from CaseWare/CM?
 1C.10	How does CVS differ from Sublime?
 1C.11	How does CVS differ from PVCS?
 1C.12	How does CVS differ from CMVC?


 **** Answers:


 1C.1	How does CVS differ from RCS?

	CVS uses RCS to do much of its work and absolutely all the work
	of changing the underlying RCS files in the Repository.

	RCS comprises a set of programs designed to keep track of changes
	to individual files.  Of course, it also allows you to refer to
	multiple files on the command line, but they are handled by
	iterating over individual files.  There is no pretense of
	coordinated interaction among groups of files.

	CVS's main intent is to provide a set of grouping functions that
	allow you to treat a collection of RCS files as a single object.
	Of course, CVS also has to do a lot of iteration, but it tries
	its best to hide that it is doing so.  In addition, CVS has some
	truly group-oriented facets, such as the modules file and the CVS
	administrative files that refer to a whole directory or module.

	One group aspect that can be a bit confusing is that a CVS branch
	is not the same as an RCS branch.  To support a CVS branch, CVS
	uses "tags" (what RCS calls "symbols") and some local state,
	in addition to RCS branches.

	Other features offered by CVS that are not supported directly by
	RCS are

	     1. Automatic determination of the state of a file, (e.g.
		modified, up-to-date with the Repository, already tagged
		with the same string, etc.)  which helps in limiting the
		amount of displayed text you have to wade through to
		figure out what changed and what to do next.

	     2. A copy-modify-merge scheme that avoids locking the files
		and allows simultaneous development on a single file.

	     3. Serialization of commits.  CVS requires you to merge all
		changes committed (via "update") since you checked out
		your working copy of the file.	Although it is still
		possible to commit a file filled with old data, it is less
		likely than when using raw RCS.

	     4. Relatively easy merging of releases from external Vendors.


 1C.2	How does CVS differ from SCCS?

	SCCS is much closer to RCS than to CVS, so some of the previous
	entry applies.

	You might want to take a look at Walter Tichy's papers on RCS,
	which are referred to in the RCS man pages.

	[[More info here?]]


 1C.3	How does CVS differ from ClearCase?

	ClearCase is a distributed client-server version control system.
	ClearCase is a variant DSEE tools, formerly available on Apollo
	platforms.  The ClearCase tool set includes a few X-based
	interface tools, a command-line interface, and C programmer API.
	It is currently available on Sun, HP, SGI and OSF/1 platforms.

	ClearCase uses a special Unix filesystem type, called "mvfs"
	for "multi-version file system".  Conceptually, mvfs adds
	another dimension to a regular Unix filesystem.	 The new
	axis is used to store the different versions of files and to
	provide a tree-hierarchical view of a collection of objects that
	might be scattered across any number of separate hosts on your
	local network.

	Each user acquires a "view" into the file database by creating a
	special mvfs mount point on their machine.  Each view has a
	"configuration spec" containing a set of selection rules that
	specify the particular version of each file to make visible in
	that view.  You can think of a "view" as a work area in CVS, except
	that the files don't really exist on your local disk until you
	modify them.  This technique conserves disk space because it
	doesn't keep private copies of read-only files.

	Another advantage is that a view is "transparent" in the sense that
	all of the files in a "view" appear to be regular Unix files to
	other tools and Unix system calls.  An extended naming convention
	allows access to particular versions of a file directly:
	"test.cc@@/main/bugfix/3" identifies the third version of test.c
	on the bugfix branch.

	ClearCase supports both the copy-modify-merge model of CVS (by
	using what are called "unreserved checkouts" and the
	checkin/checkout development model with file locking.  Directories
	are version-controlled objects as well as files.  A graphical merge
	tool is provided.  Like RCS, ClearCase supports branches, symbolic
	tags, and delta compression.  ASCII as well as binary files are
	supported, and converters from RCS, SCCS, DSEE formats are also
	included.

	A make-compatible build facility is provided that can identify
	common object code and share it among developers.  A build
	auditing feature automatically records file dependencies by
	tracking every file that is opened when producing a derived
	object, thus making explicit dependency lists unnecessary.  Pre-
	and post-event triggers are available for most ClearCase
	operations to invoke user programs or shell scripts.  User-defined
	attributes can be assigned to any version or object.  Hyper-links
	between version controlled objects can record their relationship.

	For more information, contact:

	  Atria Software, Inc.
	  24 Prime Park Way
	  Natick, MA 01760
	  info@atria.com

	  (508) 650-1193 (phone)
	  (508) 650-1196 (fax)

				Originally contributed by Steve Turner
				Edited by the author of this FAQ.


#1C.4	How does CVS differ from TeamWare/SparcWorks?

	TeamWare is a configuration management tool from Sun Microsystems,
	a part of SparcWorks.  It uses the same copy and merge model as
	CVS.  The central abstraction is a workspace, which corresponds to
	either a CVS branch or a checked out module.  TeamWare allows you
	to manipulate workspaces directly, including moving and merging
	code between workspaces.  You can put your workspace on tape and
	continue to work with it at home, just like you can with CVS.
	TeamWare is built upon and compatible with SCCS.

	TeamWare provides both a command line interface and a graphical
	interface.  The CodeManager tool will display the project as a
	tree of workspaces, and allows you to manipulate them with drag
	and drop.  The other tools are VersionTool that displays and
	manipulates a dag with a version history of a single file,
	CheckPoint that will create symbolic tags, MakeTool, a make
	compatible tool with a GUI, and FileMerge which will interactively
	merge files when needed (like emerge for emacs).  If you have a
	sun, you can try /usr/old/mergetool for an old SunView version of
	FileMerge.

	Email: sunprosig@sun.com

				Originally extracted from TeamWare
				Marketing literature by Per Abrahamsen.
				Edited by the author of this FAQ.


	For more information, contact:

	  SunExpress, Inc.
	  P.O. Box 4426
	  Bridgeton, MO 63044-9863
	  (800)873-7869


 1C.5	How does CVS differ from Aegis?

	Aegis appears to be a policy-setting tool that allows you to use
	other sub-programs (make, RCS, etc.) to implement pieces of the
	imposed policy.

	The initial document seems to say that most Unix tools are
	inadequate for use under Aegis.

	It is not really similar to CVS and requires a different mindset.

	[[Need more info here.]]


 1C.6	How does CVS differ from Shapetools?

	Shapetools includes a build mechanism (called Shape, not
	surprisingly) that is aware of the version mechanism, and some
	dependency tracking.  It is based on a file system extension
	called Attributed File System, which allows arbitrary-sized
	"attributes" to be associated with a file.  Files are version
	controlled in a manner similar to RCS.	Configurations are managed
	through the Shapefile, an extension of the Makefile syntax and
	functionality.	Shape includes version selection rules to allow
	sophisticated selection of component versions in a build.

	Shapetools' concurrency control is pessimistic, in contrast to
	that of CVS.  Also, there's very limited support for branching and
	merging.  It has a built-in policy for transitioning a system from
	initial development to production.

				Contributed by Don Dwiggins


 1C.7	How does CVS differ from TeamNet?

	TeamNet is a configuration management tool from TeamOne.

	For more information, contact:

	  TeamOne
	  710 Lakeway Drive, Ste 100
	  Sunnyvale, CA 94086
	  (800) 442-6650

				Contributed by Steve Turner


 1C.8	How does CVS differ from ProFrame?

	ProFrame is a new system integration framework from IBM.
	ProFrame is compliant with the CFI (CAD Framework Initiative)
	industry standards, including the Scheme extension language.

	ProFrame consists of three major components: (1) the Process
	Manager that automates your local design methodology (2) the
	Design Data Manager handles configuration management, and (3)
	Inter-tool Communication to provide a communication path among
	tools running on heterogeneous servers.

	The Design Data Manager(2) is probably the appropriate
	component to compare to CVS.  The Design Data Manager provides
	version control with checkin/checkout capability,
	configuration management, and data dependency tracking.	 A
	graphical data selection interface is provided.	 Using this
	interface, you may create and manipulate objects and hierarchy
	structures, view the revision history for an object, and view
	and assign attributes to a design object.

	The ProFrame server currently runs only on RS6000, but clients
	may be a wide variety of Unix platforms.  Contact IBM for the
	latest platform information.

	For more information, contact:

	  IBM
	  EDA Marketing and Sales
	  P.O. Box 950, M/S P121
	  Poughkeepsie, NY 12602
	  (800) 332-0066


				Contributed by Steve Turner
			[extracted from the ProFrame 1.1.0 datasheet]


 1C.9	How does CVS differ from CaseWare/CM?

	CaseWare/CM is a software configuration management product
	from CaseWare, Inc.  CaseWare/CM may be customized to support
	a wide variety of methodologies, including various phases of
	the software lifecycle, and different access rights for users.

	A GUI is provided to view version histories and
	configurations.	 A merge tools is also included.  CaseWare
	supports type-specific lifecycles, which allows different types
	of files to move through different lifecycles.	Also provided
	is a build facility to support automatic dependency analysis,
	parallel, distributed, and remote builds, and variant
	releases.

	CaseWare/CM has been integrated with other CASE tools,
	including FrameMaker, ALSYS Ada, CodeCenter/Object Center, HP
	SoftBench, and Software Through Pictures.  CaseWare also
	offers CaseWare/PT, a problem tracking system to integrate
	change requests with configuration management.

	Multiple vendors and operating systems are supported.

	For more information, contact:

	  CaseWare, Inc.
	  108 Pacifica, 2nd Floor
	  Irvine, CA  92718-3332
	  (714) 453-2200 (phone)
	  (714) 453-2276 (fax)

				Contributed by Steve Turner
			[extracted from the CaseWare/CM data sheet]


 1C.10	How does CVS differ from Sublime?

	Produced by AT&T.

	[[Need more info here.]]


 1C.11	How does CVS differ from PVCS?

	PVCS works on single files like RCS and SCCS, CVS works on
	complete subsystems.  PVCS has a make utility (called a
	configuration builder), CVS does not.  PVCS has a GUI interface
	for Unix, DOS, OS/2, and MS Windows.

		Intersolv, Inc.
		1700 NW 167th Place
		OR 97006

				Contributed by Per Abrahamsen
			[Extracted from Intersolv Marketing literature.]


 1C.12	How does CVS differ from CMVC?

	CMVC is an IBM Configuration Management and Version Control
	system.	 (Though I'm not certain that's the right acronym
	expansion.)  It runs on Suns, HPs, RS6000s, OS/2 and Windows.

	Other than revision control, it apparently has features to manage
	releases, bug tracking and the connection between alterations and
	reported bugs and feature requests.  It is a client/server system,
	based on a choice of commercial Relational Database systems, and
	it provides a Motif or command line interface.

	Unlike CVS, it uses a strict locking protocol to serialize source
	code alterations.


----------------
-- Section 1D --	What do you mean by . . .? (Definitions)
----------------

 **** Questions:

 1D.1	What are "The Repository", "$CVSROOT" and "CVSROOT"?
 1D.2	What is an RCS file?
 1D.3	What is a working file?
 1D.4	What is a working directory (or working area)?
 1D.5	What is "checking out"?
 1D.6	What is a revision?
 1D.7	What is a "Tag"?
 1D.8	What are "HEAD" and "BASE"?
 1D.9	What is a Branch?
 1D.10	What is "the trunk"?
 1D.11	What is a module?
 1D.12	What does "merge" mean?


 **** Answers:


 1D.1	What are "The Repository", "$CVSROOT" and "CVSROOT"?

	The Repository is a directory tree containing the CVS
	administrative files and all the RCS files that constitute
	"imported" or "committed" work.	 The Repository is kept in a
	shared area, separate from the working areas of all developers.

	Users of CVS must set their "CVSROOT" environment variable to the
	absolute pathname of the head of the Repository.  Most command
	line interpreters replace an instance of "$CVSROOT" with the value
	of the "CVSROOT" environment variable.	By analogy, in this
	document "$CVSROOT" is used as shorthand for "the absolute
	pathname of the directory at the head of the Repository".

	One of the things found in $CVSROOT is a directory named CVSROOT.
	It contains all the "state", the administrative files, that CVS
	needs during execution.	 The "modules", "history", "commitinfo",
	"loginfo" and other files can be found there.  See 4B.2 for more
	information about CVSROOT files.


 1D.2	What is an RCS file?

	An RCS file is a text file containing the source text and the
	revision history for all committed revisions of a source file.	It
	is stored separately from the working files, in a directory
	hierarchy, called the Repository.

	RCS is the "Revision Control System" that CVS uses to manage
	individual files.  RCS file names normally end in ",v", but
	that can be altered (via the RCS -x option) to conform to file
	naming standards on platforms with unusual filename limitations.


 1D.3	What is a working file?

	A working file is a disk file containing a checked-out copy of a
	source file that earlier had been placed under CVS.  If the
	working file has been edited, the changes since the last committed
	revision are invisible to other users of CVS.


 1D.4	What is a working directory (or working area)?

	A working directory is the place where you work and the place
	from which you "commit" files.

	The "checkout" command creates a tree of working directories,
	filling them with working files.  Each working directory contains
	a sub-directory named ./CVS containing three administrative files,
	which are created by "checkout" and are always present:

	./CVS/Entries
		contains information about working files.

	./CVS/Repository
		contains the location of the directory within the
		Repository that was used to create the working directory.

	./CVS/Root
		contains the value of $CVSROOT at the time you created
		the working directory.

	Other files may also appear in ./CVS depending on the state of
	your working directory:

	./CVS/Tag
		contains the "sticky tag" associated with the whole
		directory.  See 3A.2 for its main purpose.
		[Created by "checkout" or "update" when using "-r <tag>".]
		[Deleted by "checkout" or "update" when using '-A'.]

	./CVS/Entries.Static
		contains a fixed list of working files.	 If this file
		exists, an "update" doesn't automatically bring newly
		added files out of the Repository.
		[Created and maintained by hand.]

	./CVS/Checkin.prog
		contains a program to run whenever anything in the
		working directory is committed.
		[Created by checkout if "-i <prog>" appears in the
		 modules file for the checked-out module.]

	./CVS/Update.prog
		contains a program to run whenever anything in the
		working directory is updated.
		[Created by checkout if "-u <prog>" appears in the
		 modules file for the checked-out module.]

	./CVS/<file>,p
	./CVS/<file>,t
		contain (possibly zero-length) state information about an
		"add" that has not been committed.
		[Created by "add".]
		[Deleted by "commit" or "remove".]


 1D.5	What is "checking out"?

	"Checking out" is the act of using the "checkout" command to
	copy a particular revision from a set of RCS files into your
	working area.  You normally execute "checkout" only once per
	working directory (or tree of working directories), maintaining
	them thereafter with the "update" command.

	See section 3C on the "checkout" command.


 1D.6	What is a revision?

	A "revision" is a version of a file that was "committed"
	("checked in", in RCS terms) some time in the past.  CVS (and
	RCS) can retrieve any file that was committed by specifying its
	revision number or its "tag" ("symbolic name", in RCS terms).

	In CVS, a "tag" is more useful than a revision number.	It usually
	marks a milestone in development represented by different revision
	numbers in different files, all available as one "tagged"
	collection.

	Sometimes the word "revision" is used as shorthand for "the file
	you get if you retrieve (via "checkout" or "update") the given
	revision from the Repository."


 1D.7	What is a "Tag"?

	A "Tag" is a symbolic name, a synonym or alias for a
	particular revision number in a file.  The CVS "tag" command
	places the same "Tag" on all files in a working directory,
	allowing you to retrieve those files by name in the future.

	The CVS "Tag" is implemented by applying RCS "symbols" to each
	individual file.  The Tags on a file (or collection of files) may
	be displayed using the "log" command.


 1D.8	What are "HEAD" and "BASE"?

	HEAD and BASE are built-in tags that don't show up in the "log"
	or "status" listings.  They are interpreted directly by CVS.

	"HEAD" refers to the latest revision on the current branch in the
	Repository.  The current branch is either the main line of
	development, or a branch in development created by placing a
	branch tag on a set of files and checking out that branch.

	"BASE" refers to the revision on the current branch you last
	checked out, updated, or committed.  If you have not modified
	your working file, "BASE" is the committed revision matching it.

	Most of the time BASE and HEAD refer to the same revision.  They
	can become different in two ways:

	1. Someone else changed HEAD by committing a new revision of your
	   file to the Repository.  You can pull BASE up to equal HEAD by
	   executing "update".

	2. You moved BASE backward by executing "checkout" or "update"
	   with the option "-r <rev/tag>" or "-D <date>".  CVS records a
	   sticky tag and moves your files to the specified earlier
	   revision.  You can clear the sticky tag and pull BASE up to
	   equal HEAD again by executing "update -A".


 1D.9	What is a Branch?

	In general, a branch is any mechanism that allows one or more
	developers to modify a file without affecting anyone other than
	those working on the same branch.

	There are four kinds of "branch" CVS can manage:

	1. The Vendor Branch.

	   A single vendor branch is supported.	 The "import" command
	   takes a sequence of releases from a source code vendor (called
	   a "vendor" even if no money is involved), placing them on a
	   special "Vendor" branch.  The Vendor branch is considered part
	   of the "Main line" of development, though it must be merged
	   into locally modified files on the RCS Main branch before the
	   "import" is complete.

	   See Section 3H ("import").

	2. Your Working directory.

	   A checked-out working directory, can be treated like a private
	   branch.  No one but you can touch your files.  You have
	   complete control over when you include work committed by
	   others.  However, you can't commit or tag intermediate versions
	   of your work.

	3. A Development branch.

	   A group of developers can share changes among the group,
	   without affecting the Main line of development, by creating a
	   branch.  Only those who have checked-out the branch see the
	   changes committed to that branch.  This kind of branch is
	   usually temporary, collapsing (i.e. merge and forget) into the
	   Main line when the project requiring the branch is completed.

	   You can also create a private branch of this type, allowing an
	   individual to commit (and tag) intermediate revisions without
	   changing the Main line.  It should be managed exactly like a
	   Development Branch -- collapsed into the Main line (or its
	   parent branch, if that is not the Main Branch) and forgotten
	   when the work is done.

	4. A Release branch.

	   At release time, a branch should be created marking what was
	   released.  Later, small changes (sometimes called "patches")
	   can be made to the release without including everything else on
	   the Main line of development.  You avoid forcing the customer
	   to accept new, possibly untested, features added since the
	   release.  This is also the way to correct bugs found during
	   testing in an environment where other developers have continued
	   to commit to the Main line while you are testing and packaging
	   the release.

	   Although the internal format of this type of branch (branch tag
	   and RCS branches) is the same as in a development branch, its
	   purpose and the way it is managed are different.  The major
	   difference is that a Release branch is normally Permanent.
	   Once you let a release out the door to customers, or to the
	   next stage of whatever process you are using, you should retain
	   forever the branch marking that release.

	   Since the branch is permanent, you cannot incorporate the
	   branch fixes into the Main line by "collapsing" (merging and
	   forgetting) the release branch.  For large changes to many
	   files on the release branch, you will have to perform a branch
	   merge using "update -j <rev> -j <rev>".  (See 4C.7)

	   The most common way to merge small changes back into Main line
	   development is to make the change in both places
	   simultaneously.  This is faster than trying to perform a
	   selective merge.

	See 1D.12 (merges) and Section 4C, on Branching for more info.


 1D.10	What is "the trunk"?

	Another name for the RCS Main Branch.  The RCS Main Branch is
	related, but not equivalent, to both the CVS Main branch and what
	developers consider to be the Main line of development.
	See 3H.3 and Section 4C on Branching.


 1D.11	What is a module?

	In essence, a module is a name you hand to the "checkout" command
	to retrieve one or more files to work on.  It was originally
	intended to be a simple, unique name in the "modules" file
	attached to a directory or a subset of files within a directory.

	The module idea is now a somewhat slippery concept that can be
	defined in two different ways:

	A. A module is an argument to "checkout".  There are three types:

	   1. An entry in the modules file.  A "module" name as described
	      in 'B.' below.

	   2. A relative path to a directory or file in the Repository.

	   3. A mixed-mode string of "modulename/relative-path".
	      Everything up to the first slash ('/') is looked up as a
	      module.  The relative path is appended to the directory
	      associated with the module name and the resulting path is
	      checked out as in #2 above.


	B. A module is a unique (within the file) character string in the
	   first column of the modules file.  There are five types:

	   1. A name for a directory within the Repository that
	      allows you to ignore the parent directories above it.

	      Example:

		  emacs	 gnu/emacs


	   2. A name for a subset of the files within such a directory.

	      Example:

		  ls	unix/bin Makefile ls.c

	      The 2nd through Nth strings in the above can be files,
	      directories or module substitutions.  No relative paths.

	      A module substitution occurs when you use a '&module-name'
	      reference.  The module-name referred to is logically
	      substituted for the '&module-name' string.


	   3. A relative pathname to a directory within the Repository
	      which, when checked out, creates an image of part of the
	      Repository structure in your current directory.

	      Example:

		  gnu/emacs -o /bin/emacs.helper gnu/emacs

	      The files checked out are exactly the same as the files
	      "checkout" would retrieve if the path weren't even in the
	      modules file.  The only reason to put this kind of relative
	      pathname into the modules file is to hook one of the helper
	      functions onto it.


	   4. A relative pathname to a single file within the Repository
	      which, when checked out, creates something you probably
	      don't want:  It creates a directory by the name of the file
	      and puts the file in it.

	      Example:

		  gnu/emacs/Makefile -o /bin/emacs.helper gnu/emacs Makefile

	      The file checked out is the same as what you would get if
	      you handed the relative pathname to the "checkout" command.
	      But it puts it in a strange place.  The only reason to do
	      this is to hook a helper function onto a specific file name.


	   5. An alias consisting of a list of any of the above, including
	      other aliases, plus exceptions.

	      Example:

		  my_work  -a  emacs !emacs/tests gnu/bison unix/bin/ls.c


	      The exception "!emacs/test" above is functionally equivalent
	      to specifying "!emacs/tests" on the "checkout" command line.


	Another way to look at it is that the modules file is simply
	another way to "name" files.  The hierarchical directory
	structure provides another.  You should use whatever turns out to
	be simplest for your development group.

	See 4G.2 for some specific ideas about how to use the modules file.
	

 1D.12	What does "merge" mean?

	A merge is a way of combining changes made in two independent
	copies of a common starting file.  Checking out an RCS revision
	produces a file, so for the purposes of a merge "file" and
	"revision" are equivalent.  So, we can say there are always three
	"files" involved in a merge:

	1. The original, starting, "base" or "branch point" file.
	2. A copy of the base file modified in one way.
	3. Another copy of the base file modified in a different way.

	Humans aren't very good at handling three things at once, so the
	terminology dealing with merges can become strained.  One way to
	think about it is that all merges are performed by inserting the
	difference between a base revision and a later revision (committed
	by someone else) into your working file.  Both the "later"
	revision and your working file are presumed to have started life
	as a copy of the "base" revision.

	In CVS, there are three main types of "merge":

	1. The "update" command automatically merges revisions committed
	   by others into your working file.  In this case, the three
	   files involved in the merge are:

		Base:	 The revision you originally checked out.
		Later:	 A revision committed onto the current branch
			 after you checked out the Base revision.
		Working: Your working file.  The one lying in the working
			 directory containing changes you have made.

	2. The "update -j <branch_tag> {optional files}" command merges
	   changes made on the given branch into your working files, which
	   is presumed to be on the Main line of development.

		See 4C.6

	3. The "update -j <rev> -j <rev> {optional files}" command merges
	   the difference between two specified revisions into files in
	   your working directory.  The two revisions <rev> are usually on
	   the same branch and, when updating multiple files, they are
	   most useful when they are Tag names rather than numeric
	   revisions.

		See 4C.7




==========================================
==  Section 2	====	User Tasks    ====
==========================================

----------------
-- Section 2A --	Getting Started
----------------

 **** Questions:

 2A.1	What is the first thing I have to know?
 2A.2	Where do I work?
 2A.3	What does CVS use from my environment?
 2A.4	OK, I've been told that CVS is set up, my module is named
	"ralph" and I have to start editing.  What do I type?
 2A.5	I have been using RCS for a while.  Can I convert to CVS without
	losing my revision history?  How about converting from SCCS?


 **** Answers:

 2A.1	What is the first thing I have to know?

	Your organization has most likely assigned one or more persons to
	understand, baby-sit and administer the CVS programs and the data
	Repository.  I call these persons Repository Administrators.  They
	should have set up a Repository and "imported" files into it.

	If you don't believe anyone has this responsibility, or you are
	just testing CVS, then *you* are the Repository Administrator.

	If you are a normal user of CVS ask your Repository Administrator
	what module you should check out.

	Then you can work.

	If you *are* the Repository Administrator, you will want to read
	everything you can get your hands on, including this FAQ.  Source
	control issues can be difficult, especially when you get to
	branches and release planning.	Expect to feel stupid for a few
	days/weeks.

	No tool in the universe avoids the need for intelligent
	organization.  In other words, there are all sorts of related
	issues you will probably have to learn.	 Don't expect to dive in
	without any preparation, stuff your 300 Megabytes of sources into
	CVS and expect to start working.  If you don't prepare first, you
	will probably spend a few sleepless nights.


 2A.2	Where do I work?

	Wherever you have disk space.  That's one of the advantages of
	CVS: you use the "checkout" command to copy files from the
	Repository to your working directory, which can be anywhere you
	have the space.

	Your local group might have conventions for where to work.
	Ask your peers.


 2A.3	What does CVS use from my environment?

	You must set two environment variables.	 Some shells share these
	variables with local shell variables using a different syntax.
	You'll have to learn how your shell handles them.

	Variable	Value (or action)
	---------	---------------------
	CVSROOT		Absolute pathname of the head of your Repository.

	PATH		Normally set to a list of ':'-separated directory
			pathnames searched to find executables.	 You must
			make sure "cvs" is in one of the directories.

			If your CVS was built with the RCSBIN directory set
			to null (""), and you don't set the RCSBIN
			variable mentioned below, then the RCS commands
			also must be somewhere in your PATH.


	Optional variables: (Used if set, but ignored otherwise.)

	Variable	Value (or action)
	---------	---------------------
	CVSEDITOR	The name of your favorite fast-start editor
			program.  You'll be kicked into your editor to
			supply revision comments if you don't specify them
			via -m "Log message" on the command line.

	EDITOR		Used if CVSEDITOR doesn't exist.  If EDITOR
			doesn't exist, CVS uses a configured constant,
			usually, "vi".

	CVSREAD		Sets files to read-only on "checkout".

	RCSBIN		Changes where CVS finds the RCS commands.

	CVSIGNORE	Adds to the ignore list.  See Section 2D.


	Other variables used by CVS that are normally set upon login:

	Variable	Value (or action)
	---------	---------------------
	LOGNAME		Used to find the real user name.

	USER		Used to find the real user name if no LOGNAME.

	HOME		Used to determine your home directory, if set.
			Otherwise LOGNAME/USER/getuid() are used to find
			your home directory from the passwd file.

	TMPDIR		Used during import.  It might also be used if your
			platform's version of mktemp(3) is unusual, or
			you have changed the source to use tmpnam(3).



 2A.4	OK, I've been told that CVS is set up, my module is named
	"ralph" and I have to start editing.  What do I type?

		cd <where you have some space to work>
		cvs checkout ralph
		cd ralph

	And hack away.


 2A.5	I have been using RCS for a while.  Can I convert to CVS without
	losing my revision history?  How about converting from SCCS?

	If you are asking such questions, you are not a mere user of CVS,
	but one of its Administrators!	You should take a look at Section
	4A, "Installing CVS" and Section 4B, "Setting up and Managing
	the Repository".


----------------
-- Section 2B --	Common User Tasks
----------------

What I consider a "common user task" generally involves combinations
of the following commands:

	checkout, update, commit, diff, log, status, tag, add


Conventions in this section:

     1. Before each CVS command, you are assumed to have typed a "cd"
	command to move into a writable working directory.

     2. All further "cd" commands specified in the examples are assumed
	to start in the above working directory.

     3. Unless a point is being made about multiple instances, all modules
	are named <module>, all tags are named <tag> (branch tags are
	named <branch_tag>) and all files are named <file>.

	The checkout command will take a relative path name in place
	of a module name.  If you use a relative pathname in place of
	<module>, you should use the same relative path every place
	you see <module> in that example.


 **** Questions:

 2B.1	What is the absolute minimum I have to do to edit a file?
 2B.2	If I edit multiple files, must I type "commit" for each one?
 2B.3	How do I get rid of the <module> directory that "checkout" created?
 2B.4	How do I find out what has changed since my last update?
 2B.5	I just created a new file.  How do I add it to the Repository?
 2B.6	How do I merge changes made by others into my working directory?
 2B.7	How do I label a set of revisions so I can retrieve them later?
 2B.8	How do I checkout an old release of a module, directory or file?
 2B.9	What do I have to remember to do periodically?


 **** Answers:


 2B.1	What is the absolute minimum I have to do to edit a file?

	Tell your Repository Administrator to create a module covering the
	directory or files you care about.  You will be told that your
	module name is <module>.  Then type:

		cvs checkout <module>
		cd <module>
		emacs <file>	      # Isn't Emacs a synonym for edit?
		cvs commit <file>

	If you don't use modules (in my opinion, a mistake), you can check
	out a directory by substituting its relative path within the
	Repository for <module> in the example above.

	To work on a single file, you'll have to change "cd <module>" to
	"cd `dirname <module>`".


 2B.2	If I edit multiple files, must I type "commit" for each one?

	No.  You can commit a list of files and directories, including
	relative paths into multiple directories.  You can also commit
	every modified file in the current directory or in all directories
	and subdirectories from your current directory downward. See 3D.2.


 2B.3	How do I get rid of the <module> directory that "checkout" created?

	Change your directory to be the same as when you executed the
	"checkout" command that created <module>.

	If you want to get rid of the CVS control information, but leave
	the files and directories, type:

		cvs release <module>

	If you want to obliterate the entire directory, type:

		cvs release -d <module>

	("release -d" searches through the output of "cvs -n update" and
	  refuses to continue if the "update" command finds any modified
	  files or non-ignored foreign files.  Foreign directories too.)

	If you don't care about keeping "history", or checking for
	modified and foreign files, you can just remove the whole
	directory.  That's "rm -rf <module>" under Unix.


 2B.4	How do I find out what has changed since my last update?

	There are many ways to answer this.

	To find out what you've changed in your current working directory
	since your last checkout, update or commit, type:

		cvs diff

	To find out what other people have added (to your branch) since
	you last checked out or updated, type:

		cvs diff -r BASE -r HEAD

	To look at a revision history containing the comments for all
	changes, you can use the "log" command.

	You can also use "history" to trace a wide variety of events.


 2B.5	I just created a new file.  How do I add it to the Repository?

	The "update" command will mark files CVS doesn't know about in
	your working directory with a '?' indicator.

		? <file>

	To add <file> to the Repository, type:

		cvs add <file>
		cvs commit <file>

	See 3A.[2-5] and 4C.8 for branch and merge considerations.


 2B.6	How do I merge changes made by others into my working directory?

	If you are asking about other branches, see Section 4C on
	"Branching".  You will have to use the "update -j" command.

	Retrieving changes made to the Repository on the *same* branch you
	are working on is the main purpose of the "update" command.  The
	"update" command tries to merge work committed to the Repository
	by others since you last executed "checkout", "update" or "commit"
	into your working files.

	For a single file, there are six possible results when you type
	the "update" command:

	1. If the file is lying in your working directory, but is not
	   under CVS, it will do nothing but print:

		? <file>

	2. If neither you nor anyone else has committed changes to <file>,
	   since your last "checkout", "update" or "commit", "update"
	   will print nothing and do nothing.

	3. If you have made no changes to a working file, but you or
	   others have committed changes to the Repository since your last
	   "checkout", "update" or "commit" of this working file, CVS will
	   remove your working file and replace it with a copy of the
	   latest revision of that file in the Repository.  It will print:

		U <file>

	   You might want to examine the changes (using the CVS "diff"
	   command) to see if they mesh with your own in related files.

	4. If you have made changes to a working file, but no one has
	   changed your BASE revision (the revision you retrieved from the
	   Repository in your last "checkout", "update" or "commit"),
	   "update" will print:

		M <file>

	   Nothing changes.  You were told that you have a modified
	   file in your directory.

	5. If you have made changes to your working file and you or others
	   have committed changes to the Repository, but in different
	   sections of the file, CVS will merge the changes stored in the
	   Repository since your last "checkout", "update" or "commit"
	   into your working file.  "update" will print:

		RCS file: /Repository/module/<file>
		retrieving revision 1.X
		retrieving revision 1.Y
		Merging differences between 1.X and 1.Y into <file>
		M <file>

	   If you execute "diff" before and after this step, you should
	   see the same output, since both the base file and your working
	   file changed in parallel.  This is one of the few times the
	   otherwise nonsensical phrase "same difference" means something.

	6. If both you and those who committed files (since your last
	   checkout, update or commit) have made changes to the same
	   section of a file, CVS will merge the changes into your file as
	   in #5 above, but it will leave conflict indicators in the file.
	   "update" will print:

		RCS file: /Repository/module/<file>
		retrieving revision 1.X
		retrieving revision 1.Y
		Merging differences between 1.X and 1.Y into <file>
		rcsmerge warning: overlaps during merge
		cvs update: conflicts found in <file>
		C <file>

	   This is a "conflict".  The file will contain markers
	   surrounding the overlapping text.  The 'C' conflict indicator
	   is sticky -- subsequent "update" commands will continue to show
	   a 'C' until you edit the file.

	   You must examine the overlaps with care and resolve the problem
	   by analyzing how to retain the features of both changes.  See
	   2D.7 and 3P.6 for more details on conflict resolution.


 2B.7	How do I label a set of revisions so I can retrieve them later?

	To "tag" the BASE revisions (the ones you last checked out,
	updated, or committed) you should "cd" to the head of the working
	directory you want to tag and type:

		cvs tag <tag>

	It recursively walks through your working directory tagging the
	BASE revisions of all files.

	To "tag" the latest revision on the Main branch in the
	Repository, you can use the following from anywhere:
	(No "cd" is required -- it works directly on the Repository.)

		cvs rtag <tag> <module>


 2B.8	How do I checkout an old release of a module, directory or file?

	Module names and directories are simply ways to name sets of
	files.	Once the names are determined, there are 6 ways to specify
	which revision of a particular file to check out:

	1. By tag or symbolic name, via the "-r <tag>" option.

	2. By date, via the "-D <date>" option.

	3. By branch tag (a type of tag with a magic format), via the
	   "-r <branch_tag>" option.

	4. By date within a branch, via the "-r <branch_tag>:<date>"
	   option.

	5. By an explicit branch revision number ("-r <rev>"), which
	   refers to the latest revision on the branch.	 This isn't really
	   an "old" revision, from the branch's perspective, but from the
	   user's perspective the whole branch might have been abandoned
	   in the past.

	6. An explicit revision number: "-r <rev>" Though this works, it
	   is almost useless for more than one file.


	You type:

		cvs checkout <option-specified-above> <module>
		cd <module>


 2B.9	What do I have to remember to do periodically?

	You should execute "cvs -n update" fairly often to keep track of
	what you and others have changed.  It won't change anything -- it
	will just give you a report.

	Unless you are purposely delaying the inclusion of others' work,
	you should execute "update" once in a while and resolve the
	conflicts.  It is not good to get too far out of sync with the
	rest of the developers working on your branch.

	It is assumed that your system administrators have arranged for
	editor backup and Unix temp files (#* and .#*) to be deleted after
	a few weeks.  But you might want to look around for anything else
	that is ignored or hidden.  Try "cvs -n update -I !" to see all
	the ignored files.

	If you are the Repository Administrator, see 4B.16 on
	Administrator responsibilities.


----------------
-- Section 2C --	Less Common User Tasks
----------------

What I consider a "less common user task" generally involves one or
more of the following commands:

	history, import, export, rdiff, release, remove, rtag


 **** Questions:

 2C.1	Can I create non-CVS sub-directories in my working directory?
 2C.2	How do I add new sub-directories to the Repository?
 2C.3	How do I remove a file I don't need?
 2C.4	How do I rename a file?
 2C.5	How do I make sure that all the files and directories in my
	working directory are really in the Repository?
 2C.6	How do I create a branch?
 2C.7	How do I modify the modules file?  How about the other files in
	the CVSROOT administrative area?
 2C.8	How do I split a file into pieces, retaining revision histories?


 **** Answers:


 2C.1	Can I create non-CVS sub-directories in my working directory?

	Yes.  Unless the directory exists in the Repository, "update" will
	skip over them and print a '?' the way it does for files you
	forgot to add.	You can avoid seeing the '?' by adding the name
	of the foreign directory to the ./.cvsignore file, just ask you
	can do with files.

	If you explicitly mention a foreign directory on the "update"
	command line, it will traverse the directory and waste a bit of
	time, but if any directory or sub-directory lacks the ./CVS
	administrative directory, CVS will print an error and abort.


 2C.2	How do I add new sub-directories to the Repository?

	The "add" command will work on directories.  You type:

	    mkdir <dir>
	    cvs add <dir>

	It will respond:

	    Directory /Repos/<dir> added to the repository

	and will create both a matching directory in the Repository and a
	./CVS administrative directory within the local <dir> directory.


 2C.3	How do I remove a file I don't need?

	(See the questions in Section 4B on removing files from the
	 Repository.)

	You type:

		rm <file>
		cvs remove <file>

	CVS registers the file for removal.  To complete the removal, you
	must type:

		cvs commit <file>

	CVS moves the file to the Attic associated with your working
	directory.  Each directory in the Repository stores its deleted
	files in an Attic sub-directory.  A normal "checkout" doesn't
	look in the Attic, but if you specify a tag, a date or a
	revision, the "checkout" (or "update") command will retrieve
	files from the Attic with that tag, date or revision.


 2C.4	How do I rename a file?

	CVS does not offer a way to rename a file in a way that CVS can
	track later.  See Section 4B for more information.

	Here is the best (to some, the only acceptable) way to get the
	effect of renaming, while preserving the change log:

	   1. Copy the RCS (",v") file directly in the Repository.

		cp $CVSROOT/<odir>/<ofile>,v $CVSROOT/<ndir>/<nfile>,v

	      By duplicating the file, you will preserve the change
	      history and the ability to retrieve earlier revisions of the
	      old file via the "-r <tag/rev>" or "-D <date>" options to
	      "checkout" and "update".

	   2. Remove the old file using CVS.

		cd <working-dir>/<odir>
		rm <ofile>
		cvs remove <ofile>
		cvs commit <ofile>

	      This will move the <ofile> to the Attic associated with
	      <odir>.

	   3. Retrieve <nfile> and remove all the Tags from it.

	      By stripping off all the old Tags, "checkout -r" and
	      "update -r" won't retrieve revisions Tagged before
	      the renaming.

		cd <working-dir>/<ndir>
		cvs update <nfile>
		cvs log <nfile>			# Save the list of Tags
		cvs tag -d <tag1> <nfile>
		cvs tag -d <tag2> <nfile>
		. . .


	This technique can be used to rename files within one directory or
	across different directories.  You can apply this idea to
	directories too, as long as you apply the above to each file and
	don't delete the old directory.

	Of course, you have to change your build system (e.g. Makefile) in
	your <working-dir> to know about the name change.

	Warning: Stripping the old tags from the copied file will allow
	"-r <tag>" to do the right thing, but you will still have problems
	with "-D <date>" because there is no place to store the "deletion
	time".	See 5B.3 for more details.


 2C.5	How do I make sure that all the files and directories in my
	working directory are really in the Repository?

	A "cvs update", or "cvs -n update" (which won't modify your
	working directory) will display foreign elements, which have no
	counterpart in the Repository, preceded by a '?'.  To register
	foreign directories, you can use "cvs add".  To register foreign
	files, you can use "cvs add" followed by "cvs commit".

	You could also checkout your module, or the Repository directory
	associated with your working directory, a second time into another
	work area and compare it to your working directory using the
	(non-CVS) "diff -r" command.

	By default many patterns of files are ignored.	If you create a
	file named "core" or a file ending in ".o", it is usually
	ignored.  If you really want to see all the files that aren't in
	the Repository, you can use a special "ignore" pattern to say
	"ignore no files".  Try executing: (You may have to quote or
	backwhack (i.e. precede by '\') the '!' in your shell.)

		cvs -n update -I !

	The above command will display not only the normal modified,
	update and conflict indicators ('M', 'U', and 'C' respectively) on
	files within the Repository, but it will also display each file
	not in the Repository preceded by a '?' character.

	The '-n' option will not allow "update" to alter your working
	directory.


 2C.6	How do I create a branch?

	Type this in your working directory:

		cvs tag -b <branch_tag>

	and you will create a branch.  No files have real branches in them
	yet, but if you move onto the branch by typing:

		cvs update -r <branch_tag>

	and commit a file in the normal way:

		cvs commit <file>

	then a branch will be created in the underlying <file>,v file and
	the new revision of <file> will appear only on that branch.

	See Section 4C, on Branching.


 2C.7	How do I modify the modules file?  How about the other files in
	the CVSROOT administrative area?

	A module named "modules" has been provided in the default modules
	file, so you can type:

		cvs checkout modules
		cd modules

	Another module named CVSROOT has been provided in the default
	modules file, covering all the administrative files.  Type:

		cvs checkout CVSROOT
		cd CVSROOT

	Then you can edit your files, followed by:

		cvs commit

	If you start with the provided template for the "modules" file,
	the CVSROOT and the "modules" module will have the "mkmodules"
	program as a "commit helper".  After a file is committed to such a
	module, "mkmodules" will convert a number of standard files (See
	4B.2) in the CVSROOT directory inside the Repository into a form
	that is usable by CVS.


 2C.8	How do I split a file into pieces, retaining revision histories?

	If you and a coworker find yourselves repeatedly committing the
	same file, but never for changes in the same area of the file, you
	might want to split the file into two or more pieces.  If you are
	both changing the same section of code, splitting the file is of
	no use.	 You should talk to each other instead.

	If you decide to split the file, here's a suggestion.  In many
	ways, it is similar to multiple "renamings" as described in
	2C.4 above.

	Say you want to split <fileA>, which already in the Repository,
	into three pieces, <fileA>, <fileB> and <fileC>.

	   1. Copy the RCS (",v") files directly in the Repository,
	      creating the new files, then bring readable copies of the
	      new files into the working directory via "update".

		cp $CVSROOT/<path>/<fileA>,v $CVSROOT/<path>/<fileB>,v
		cp $CVSROOT/<path>/<fileA>,v $CVSROOT/<path>/<fileC>,v
		cvs update <fileB> <fileC>

	   2. Then remove all the <tags> from the new files by using:

		cvs log <fileB> <fileC>	      # Save the list of <tag?>
		cvs tag -d <tag1> <fileB> <fileC>
		cvs tag -d <tag2> <fileB> <fileC>
		. . .

	   3. Edit each file until it has the data you want in it.
	      This is a hand-editing job, not something CVS can handle.
	      Then commit all the files.

	      [From experience, I'd suggest making sure that only one copy
	      of each line of code exists among the three files, except
	      for "include" statements, which must be duplicated.  And
	      make sure the code compiles.]

		emacs <fileA> <fileB> <fileC>
		cvs commit <fileA> <fileB> <fileC>


	As in the "rename" case, by duplicating the files, you'll preserve
	the change history and the ability to retrieve earlier revisions.

	Of course, you have to alter your build system (e.g. Makefiles) to
	take the new names and the change in contents into account.



----------------
-- Section 2D --	General Questions
----------------

 **** Questions:

 2D.1	How do I see what CVS is trying to do?
 2D.2	If I work with multiple modules, should I check them all out and
	commit them occasionally?  Is it OK to leave modules checked out?
 2D.3	What is a "sticky" tag? What makes it sticky? How do I loosen it?
 2D.4	How do I get an old revision without updating the "sticky tag"?
 2D.5	What operations disregard sticky tags?
 2D.6	Is there a way to avoid reverting my Emacs buffer after
	committing a file?  Is there a "cvs-mode" for Emacs?
 2D.7	How does conflict resolution work?  What *really* happens if two
	of us change the same file?
 2D.8	How can I tell who has a module checked out?
 2D.9	Where did the .#<file>.1.3 file in my working directory come from?
 2D.10	What is this "ignore" business?	 What is it ignoring?
 2D.11	Is there a way to set user-specific configuration options?
 2D.12	Is it safe to interrupt CVS using Control-C?
 2D.13	How do I turn off the "admin" command?
 2D.14	How do I turn off the ability to disable history via "cvs -l"?
 2D.15	How do I keep certain people from accessing certain directories?


 **** Answers:


 2D.1	How do I see what CVS is trying to do?

	The '-t' option on the main "cvs" command will display every
	external command (mostly RCS commands and file deletions) it
	executes.  When combined with the '-n' option, which prevents the
	execution of any command that might modify a file, you can see
	what it will do before you let it fly.	The '-t' option will *not*
	display every internal action, only calls to external programs.

	To see a harmless example, try typing:

		cvs -nt update

	Some systems offer a "trace" or "truss" command that will display
	all system calls as they happen.  This is a *very* low-level
	interface that does not normally follow the execution of external
	commands, but it can be useful.

	The most complete answer is to read the source, compile it
	with the '-g' option and step through it under a debugger.


 2D.2	If I work with multiple modules, should I check them all out and
	commit them occasionally?  Is it OK to leave modules checked out?

	The simple answers are "Yes."

	There is no reason to remove working directories, other than to
	save disk space.  As long as you have committed the files you
	choose to make public, your working directory is just like any
	other directory.

	CVS doesn't care whether you leave modules checked out or not.
	The advantage of leaving them checked out is that you can quickly
	visit them to make and commit changes.


 2D.3	What is a "sticky" tag? What makes it sticky? How do I loosen it?

	When you execute "update -r <tag>", CVS remembers the <tag>.  It
	has become "sticky" in the sense that until you change it or
	remove it, the tag is remembered and used in references to the
	file as if you had typed "-r <tag>" on the command line.

	It is most useful for a <branch_tag>, which is a sticky tag
	indicating what branch you are working on.

	A revision number ("-r <rev-number>") or date ("-D <date>") can
	also become sticky when they are specified on the command line.

	A sticky tag, revision or date remains until you specify another
	tag, revision or date the same way.  The "update -A" command
	moves back to the Main branch, which has the side-effect of
	clearing all sticky items on the updated files.

	The "checkout" command creates sticky tags, revisions and dates
	the same way "update" does.

	Also, the '-k' option records a "sticky" keyword option that
	is used in further "updates until "update -A" is specified.


 2D.4	How do I get an old revision without updating the "sticky tag"?

	Use the '-p' option to "pipe" data to standard output.	The
	command "update -p -r <tag/rev>" sends the selected revision to
	your standard output (usually the terminal, unless redirected).
	The '-p' affects no disk files, leaving a "sticky tag" unaltered
	and avoiding all other side-effects of a normal "update".

	If you want to save the result, you can redirect "stdout" to a
	file using your shell's redirection capability.	 In most shells
	the following command works:

	    cvs update -p -r <tag/rev> filename > diskfile


 2D.5	What operations disregard sticky tags?

	The functions that routinely disregard sticky tags are:

	     1. Those that work directly on the Repository or its
		administrative files:

		admin	rtag	log	status	remove	history

	     2. Those that take Tags or revisions as arguments and ignore
		everything else: (They also never *set* a sticky tag.)

		rdiff	import	export

	     3. The "release" command itself ignores sticky tags, but it
		calls "cvs -n update" (which *does* pay attention to a
		sticky tag) to figure out what inconsistencies exist in
		the working directory.	If no discrepancies exist between
		the files you originally checked out (possibly marked by a
		sticky tag) and what is there now, "release -d" will
		delete them all.

	     4. The "tag" command works on the revision lying in the
		working directory however it got there.	 That the revision
		lying there might happen to have a sticky tag attached to
		it is not the "tag" command's concern.


	The main function that *does* read and write sticky tags is the
	"update" command.  You can avoid referring to or changing the
	sticky tag by using the '-p' option, which sends files to your
	terminal, touching nothing else.

	The "checkout" command sets sticky tags when checking out a new
	module and it acts like "update" when checking out a module into
	an existing directory.

	The "diff" and "commit" commands use the sticky tags, unless
	overridden on the command line.	 They do not set sticky tags.
	Note that you can only "commit" to a file checked out with a
	sticky tag, if the tag identifies a branch.

	There are really two types of sticky tags, one attached to
	individual files (in the ./CVS/Entries file) and one attached to
	each directory (in the ./CVS/Tag file).	 They can differ.

	The "add" command registers the desire to add a new file.  If the
	"directory tag" (./CVS/Tag) file exists at the time of the "add",
	the value stored in ./CVS/Tag becomes the "sticky tag" on the new
	file.  The file doesn't exist in the Repository until you "commit"
	it, but the ./CVS/Entries file holds the sticky tag name from the
	time of the "add" forward.


 2D.6	Is there a way to avoid reverting my Emacs buffer after
	committing a file?  Is there a "cvs-mode" for Emacs?

	See Section 4F.1


 2D.7	How does conflict resolution work?  What *really* happens if two
	of us change the same file?

	While editing files, there is no conflict.  You are working on
	separate copies of the file stored in the virtual "branch"
	represented by your working directories.  After one of you commits
	a file, the other may not commit the same file until "update" has
	merged the earlier committed changes into the later working file.

	For example, say you both check out rev 1.2 of <file> and make
	change to your working files.  Your coworker commits revision 1.3.
	When you try to commit your file, CVS says:

		cvs commit: Up-to-date check failed for `<file>'

	You must merge your coworker's changes into your working file by
	typing:

		cvs update <file>

	which will produce the output described in 2B.6.

	If a conflict occurs, the filename will be shown with a status of
	'C'.  After you resolve any overlaps caused by the merging
	process, you may then commit the file.	See 3P.6 for info on
	"sticky conflicts".

	Even if you get a simple 'M', you should examine the differences
	before committing the file.  A smooth, error-free text merge is
	still no indication that the file is in proper shape.  Compile and
	test it at least.

	The answer to two obvious questions is "Yes".

	Yes, the first one who commits avoids the merge.  Later developers
	have to merge the earlier changes into their working files before
	committing the merged result. Depending on how difficult the merge
	is and how important the contending projects are, the order of
	commits and updates might have to be carefully staged.

	And yes, between the time you execute "update" and "commit" (while
	you are fixing conflicts and testing the results) someone else may
	commit another revision of <file>.  You will have to execute
	"update" again to merge the new work before committing.	 Most
	organizations don't have this problem.	If you do, you might
	consider splitting the file.  Or hiring a manager.


 2D.8	How can I tell who has a module checked out?

	If you "checkout" module names (not relative pathnames) and you
	use the release command, the "history" command will display active
	checkouts, who has them and where they were checked out.  It is
	advisory only; it can be circumvented by using the '-l' option on
	the main "cvs" command.


 2D.9	Where did the .#<file>.1.3 file in my working directory come from?

	It was created during an "update" when CVS merged changes from the
	Repository into your modified working file.

	It serves the same purpose as any "backup" file: saving your bacon
	often enough to be worth retaining.  It is invaluable in
	recovering when things go wrong.

	Say Developers A (you) and B check out rev 1.3 of file <file>.
	You both make changes -- different changes.  B commits first, so
	<file>,v in the Repository contains revisions up through 1.4.

	At this point, there are 5 (yes, five) versions of the file of
	interest to you:

	1. Revision 1.3		   (What you originally checked out.)
	2. Revision 1.4		   (What you need from developer B.)
	3. Your old working file.  (Before the update.)
	4. Your new working file.  (After the merge caused by "update".)
	5. Revision 1.5		   (Which you will commit shortly.)

	In the case where your working file was not modified, #1 and #3
	will be the same, as will #2 and #4.  In this degenerate case,
	there is no need to create #5.	The following assumes that your
	working file was modified.

	If the merge executed by the "update" caused no overlaps, and you
	commit the file immediately, #4 and #5 will be the same.  But you
	can make arbitrary changes before committing, so the difference
	between #4 and #5 might be more than just the correction of
	overlaps.  In general, though, you don't need #4 after a commit.

	But #3 (which is the one saved as ".#<file>.1.3") holds all of
	your work, independent of B's work.  It could represent a major
	effort that you couldn't afford to lose.  If you don't save it
	somewhere, the merge makes #3 *disappear* under a potential
	blizzard of conflicts caused by overlapping changes.

	I have been saved a few times, and others I support have been
	saved hundreds of times, by the ability to "diff <original file>
	<original file with only my work added>", which can be done in the
	example above by the Unix shell command:

		cvs update -p -r 1.3 <file> | diff - .#<file>.1.3

	The assumption is that the ".#" files will be useful far beyond
	the "commit" point, but not forever.  You are expected to run
	the "normal" Unix cleanup script from "cron", which removes "#*"
	and ".#*" files older than a some period chosen by your
	sysadmin, usually ranging from 7 to 30 days.

	A question was raised about the need for #3 after #5 has been
	committed, under the assumption that you won't commit files until
	everything is exactly as you like them.

	This assumes perfect humans, which violates one of the Cardinal
	rules of Software Engineering: Never assume any form of discipline
	on the part of the users of software.  If restrictions are not
	bound into the software, then you, the toolsmith, have to arrange
	a recovery path.

	In other words, I've seen every possible variety of screwup you
	can imagine in #5.  There is no way to make assumptions about
	what "should" happen.  I've seen #5 filled with zeros because of
	NFS failures, I've seen emacs core dumps that leave #5 in an
	unreasonable state, I've seen a foolish developer uppercase the
	whole file (with his "undo" size set low so he couldn't undo it)
	and decide that it would be less work to play with the
	uppercased file than to blow it away and start over.  I've even
	seen committed files with conflict markers still in them, a sure
	sign of carelessness.

	There are all sorts of scenarios where having #3 is incredibly
	useful.	 You can move it back into place and try again.


 2D.10	What is this "ignore" business?	 What is it ignoring?

	The "update" and "import" commands use collections of Unix
	wildcards to skip over files and directories matching any of those
	patterns.

	You may add to the built-in ignore list by adding lines of
	whitespace-separated wildcards to the following places:	 (They are
	read in this order.)

	1. In a file named "cvsignore" in $CVSROOT/CVSROOT.

	   A Repository Administrator uses this to add site-specific
	   files and patterns to the built-in ignore list.

	2. In a file named ".cvsignore" in your home directory.

	   For user-specific files.  For example, if you use "__" as
	   your default junk file prefix, you can put "__*" in your
	   .cvsignore file.

	   People who play around exclusively in directory trees where the
	   Makefiles are generated by "imake" or "configure" might want to
	   put "Makefile" in their ignore list, since they are all
	   generated and usually don't end up in the Repository.

	3. In the CVSIGNORE environment variable.

	   For session-specific files.

	4. Via the '-I' option on "import" or "update" commands.

	   For this-command-only files.

	5. In a file named ".cvsignore" within each directory.

	   The contents of a ".cvsignore" file in each directory is
	   temporarily added to the ignore list.  This way you can ignore
	   files that are peculiar to that directory, such as executables
	   and other generated files without known wildcard patterns.

	In any of the places listed above, a single '!' character nulls
	out the ignore list.  A Repository administrator can use this to
	override, rather than enhance, the built-in ignore list.  A user
	can choose to override the system-wide ignore list.  For example,
	if you place "! *.o *.a" in your .cvsignore file, only *.o *.a
	files, plus any files a local-directory .cvsignore file, are
	ignored.

	A variant of the ignore-file scheme is used internally during
	checkout.  "Module names" found in the modules file (or on the
	"checkout" command line) that begin with a '!' are ignored during
	checkout.  This is useful to permanently ignore (if the '!' path
	is in the modules file) or temporarily ignore (if the '!' path is
	on the command line) a sub-directory within a Repository
	hierarchy.  For example:

		cvs checkout !gnu/emacs/tests gnu/emacs

	would checkout the module (or relative path within $CVSROOT) named
	"gnu/emacs", but ignore the "tests" directory within it.


 2D.11	Is there a way to set user-specific configuration options?

	User-specific configuration is available through use of a ".cvsrc"
	file in your home directory.

	CVS searches the first column of your ~/.cvsrc file for the cvs
	command name you invoked.  If the command is found, the rest of
	the line is treated like a set of command line options, stuffed
	into the command line before the arguments you actually typed.

	For example, if you always want to see context diffs and you never
	want to have to delete a file before you run "cvs remove", then
	you should create a .cvsrc file containing the following:

		diff -c
		remove -f

	which will add the given options to every invocation of the given
	commands.

	[[The rest of this will be removed someday, when CVS changes.]]

	I would like to stop here with a comment that the command name to
	use is the full, canonical one.	 But the command that the cvsrc
	support uses is the string you typed on the command line, not the
	proper command.	 So to get the full effect of the above example,
	you should also add all the alternate command names:

		di -c
		dif -c
		rm -f
		delete -f

	There are two other limitations that will probably be fixed when
	CVS sprouts long option names:

	1. It only affects options made available on the command line.

	   There is a limited number of short options.	With long option
	   names, there is no problem.	You can have as many long options
	   as you like, affecting anything that looks malleable.

	2. The existing command line options do not come in on/off pairs,
	   so there is no easy way to override your ~/.cvsrc configuration
	   for a single invocation of a command.

	   Choosing a good set of long option pairs would fix this.


 2D.12	Is it safe to interrupt CVS using Control-C?

	It depends on what you mean by "safe".	("Ah," said Arthur,
	"this is obviously some strange usage of the word *safe* that I
	wasn't previously aware of." -- Hitchhiker's Guide to the Galaxy)

	You won't hurt the underlying RCS files and if you are executing a
	command that only *reads* data, you will have no cleanup to do.

	But you may have to hit Control-C repeatedly to stop it.  CVS uses
	the Unix "system" routine which blocks signals in the CVS parent
	process.  A single Control-C during "system" will only halt the
	child process, usually some form of RCS command.

	If you don't hit another Control-C while the CVS process has
	control, it is likely to continue onto the next task assuming that
	the earlier one did its job.  It is not enough to hit two
	Control-C's.  You might simply kill two child processes and not
	interrupt CVS at all.  Depending on the speed of your processor,
	your terminal and your fingers, you might have to hit dozens of
	Control-C's to stop the damn thing.


	Executing a CVS command, such as "commit" or "tag" that writes
	to the files is a different matter.

	Since CVS is not a full-fledged database, with what database
	people call "commit points", merely stopping the process will not
	back out the "transaction" and place you back in the starting
	blocks.	 CVS has no concept of an "atomic" transaction or of
	"backtracking", which means that a command can be half-executed.

	Hitting Control-C will usually leave lock files that you have to
	go clean up in the Repository.

	Example1:

		If you interrupt a multi-file "commit" in the middle of
		an RCS checkin, RCS will leave the file either fully
		checked-in or in its original state.  But CVS might have
		been half-way through the list of files to commit.  The
		directory or module will be inconsistent.

		To recover, you must remove the lock files, then decide
		whether you want to back out or finish the job.

		To back out, you'll have to apply the "admin -o"
		command, very carefully, to remove the newly committed
		revisions.  This is usually a bad idea, but is
		occasionally necessary.

		To finish, you can simply retype the same commit command.
		CVS will figure out what files are still modified and
		commit them.  It helps that RCS doesn't leave a file in an
		intermediate state.


	Example2:

		If you interrupt a multi-file "tag" command, you have a
		problem similar, but not equivalent, to interrupting a
		"commit".  The RCS file will still be consistent, but
		unlike "commit", which only *adds* to the RCS file, "tag"
		can *move* a tag and it doesn't keep a history of what
		revision a tag used to be attached to.

		Normally, you have little choice but to re-execute the
		command and allow it to tag everything consistently.

		You might be able to recover by carefully re-applying the
		tags via the "cvs admin -N" command, but you'll still have
		to dig up from outside sources the information you use to
		determine what tag was on what revision in what file.
		the Repository, or by using the equivalent: "cvs admin".


	Halting a new "checkout" should cause no harm.	If you don't want
	it, "release" (or rm -rf) it.  If you do want it, re-execute the
	command.  A repeated "checkout" from above a directory acts like a
	repeated "update -d" within it.

	Halting "update" half-way will give you an unpredictable
	collection of files and revisions.  To continue, you can rerun the
	update and it should move you forward into in a known state.  To
	back out, you'll have to examine the output from the first
	"update" command, take a look at each file that was modified and
	reconstruct the previous state by editing the ./CVS/Entries file
	and by using "cvs admin".  Good Luck.


 2D.13	How do I turn off the "admin" command?

	In the current revision, you'd have to edit the source code.


 2D.14	How do I turn off the ability to disable history via "cvs -l"?

	In the current revision, you'd have to edit the source code.


 2D.15	How do I keep certain people from accessing certain directories?

	If you don't try to run CVS set[ug]id, you can use Unix groups and
	permissions to limit access to the Repository.

	If you only want to limit "commit" commands, you can write a
	program to put in the "commitinfo" file.  In the "contrib"
	directory, there are a few scripts that might help you out.



========================================
==  Section 3	====	Commands    ====
========================================

This section contains questions that are easily recognized to be about a
single command, usually of the form: "Why does the 'xyz' command do this?"

Questions about "missing" features and side-effects not attributable to a
particular command are in Section 2D, "General Questions".

I won't provide patches here that are longer than a few lines.	Patches
referred to in this section are available in the FTP archive described
toward the beginning of this document.


----------------
-- Section 3A --	"add", "ad", "new"
----------------

 **** Questions:

 3A.1	What is "add" for?
 3A.2	How do I add a new file to the branch I'm working on?
 3A.3	Why did my new file end up in the Attic?
 3A.4	Now that it's in the Attic, how do I connect it to the Main branch?
 3A.5	How do I avoid the hassle of reconnecting an Attic-only file to
	the Main Branch?
 3A.6	How do I cancel an "add"?
 3A.7	What are the ./CVS/file,p and ./CVS/file,t files for?
 3A.8	How do I "add" a binary file?


 **** Answers:

 3A.1	What is "add" for?

	To add a new directory to the Repository or to register the
	desire to add a new file to the Repository.

	The directory is created immediately, while the desire to add the
	file is recorded in the local ./CVS administrative directory.  To
	really add the file to the Repository, you must then "commit" it.


 3A.2	How do I add a new file to the branch I'm working on?

	The user actions for adding a file to any branch, including the
	Main Branch, are exactly the same.

	You are in a directory checked out (or updated) with the '-A'
	option (to place you on the Main Branch) or the "-r <branch_tag>"
	option (to place you on a branch tagged with <branch_tag>).   To
	add <file> to the branch you are on, you type:

		cvs add <file>
		cvs commit <file>

	If no ./CVS/Tag file exists (the '-A' option deletes it), the
	file will be added to the Main Branch.	If a ./CVS/Tag file exists
	(the "-r <branch_tag>" option creates it), the file will be added
	to the branch named (i.e. tagged with) <branch_tag>.

	Unless you took steps to first add the file to the Main Branch,
	your new file ends up in the Attic.


 3A.3	Why did my new file end up in the Attic?

	The file is thrown into the Attic to keep it from being visible
	when you check out the Main Branch, since it was never committed
	to the Main Branch.


 3A.4	Now that it's in the Attic, how do I connect it to the Main branch?

	That can be considered a kind of "merge".  See 4C.8


 3A.5	How do I avoid the hassle of reconnecting an Attic-only file to
	the Main Branch?

	You create it on the Main Branch first, then branch it.

	If you haven't yet added the file or if you decided to delete the
	new Attic file and start over, then do the following:
	(If you added the file (or worse, the 157 files) to the Attic and
	 don't want to start over, try the procedure in 4C.8.)


	1. Temporarily remove the sticky branch information.  Either:

	   A. Move the whole directory back to the Main Branch.
	      [This might not be a good idea if you have modified files,
	       since it will require a merge in each direction.]

		cvs update -A

			*or*

	   B. Move the ./CVS/Tag file out of the way.

		mv ./CVS/Tag HOLD_Tag

	2. Add and branch the file "normally":

		cvs add <file>
		cvs commit <file>
		cvs tag -b <branch_tag> <file>

		[<branch_tag> is the same Branch Tag as you used on all
		 the other files.  Look at ./CVS/Entries or the output
		 from "cvs stat" for sticky tags.]

	3. Clean up the temporary step.

	   A. If you moved the ./CVS/Tag file, put it back.  Then
	      move the new file onto the branch where you are working.

		mv HOLD_Tag ./CVS/Tag
		cvs update -r <branch_tag> <file>

	   B. If you ran "update -A" rather than moving the ./CVS/Tag
	      file, move the whole directory (including the new file) back
	      onto the branch where you were working:

		cvs update -r <branch_tag>


 3A.6	How do I cancel an "add"?

	If you want to remove the file entirely and cancel the "add" at
	the same time, type:

		cvs remove -f <file>

	If you want to cancel the "add", but leave the file as it was
	before you typed "cvs add", then you have to fake it:

		mv <file> <file>.hold
		cvs remove <file>
		mv <file>.hold <file>


 3A.7	What are the ./CVS/file,p and ./CVS/file,t files for?

	The ./CVS/file,p and ./CVS/file,t files are created by the "add"
	command to hold command line options and message text between the
	time of the "add" command and the expected "commit".

	The ./CVS/file,p file is always null, since its function was
	absorbed by the "options" field in the ./CVS/Entries file.  If you
	put something in this file it will be used as arguments to the RCS
	"ci" command that commit uses to check the file in, but CVS itself
	doesn't put anything there.

	The ./CVS/file,t file is null unless you specify an initial
	message in an "add -m 'message'" command.  The text is handed to
	"rcs -i -t./CVS/file,t" to create the initial RCS file container.

	Both files must exist to commit a newly added file.  If the
	./CVS/file,p file doesn't exist, CVS prints an error and aborts
	the commit.  If the ./CVS/file,t file doesn't exist, RCS prints an
	error and CVS gets confused, but does no harm.

	To recover from missing ,p and ,t files, just create two
	zero-length files and rerun the "commit".


 3A.8	How do I "add" a binary file?

	If you configured CVS to use the GNU version of "diff" and
	"diff3", you only need to turn off RCS keyword expansion.

	First you turn off RCS keyword expansion for the initial checkin
	by using "add -ko".  It works like "update -ko" in creating a
	"sticky" option only for the copy of the file in the current
	working directory.

		cvs add -ko <file>

	Commit the file normally.  The sticky -ko option will be used.

		cvs commit <file>

	Then mark the RCS file in the Repository so that keyword
	expansion is turned off for all checked out versions of the file.

		cvs admin -ko <file>

	Since "admin -ko" records the keyword substitution value in the
	Repository's RCS file, you no longer need the sticky option.  You
	can turn it off with the "update -A" command, but if you were on a
	branch, you'll have to follow it "update -r <branch_tag>" to put
	yourself back on the branch.


	Managing that binary file is another problem.  See 4D.1.



----------------
-- Section 3B --	"admin", "adm", "rcs"
----------------

 **** Questions:

 3B.1	What is "admin" for?
 3B.2	Wow!  Isn't that dangerous?
 3B.3	What would I normally use "admin" for?
 3B.4	What should I avoid when using "admin"?
 3B.5	How do I restrict the "admin" command?	The -i flag in the modules
	file can restrict commits.  What's the equivalent for "admin"?
 3B.6	I backed out a revision with "admin -o" and committed a
	replacement.  Why doesn't "update" retrieve the new revision?


 **** Answers:


 3B.1	What is "admin" for?

	To provide direct access to the underlying "rcs" command (which
	is not documented in this FAQ) bypassing all safeguards and CVS
	assumptions.


 3B.2	Wow!  Isn't that dangerous?

	Yes.

	Though you can't hurt the internal structure of an RCS file using
	its own "rcs" command, you *can* change the underlying RCS
	files using "admin" in ways that CVS can't handle.

	If you feel the need to use "admin", create some test files
	with the RCS "ci" command and experiment on them with "rcs"
	before blasting any CVS files.


 3B.3	What would I normally use "admin" for?

	Normally, you wouldn't use admin at all.  In unusual
	circumstances, experts can use it to set up or restore the
	internal RCS state that CVS requires.

	You can use "admin -o" (for "outdate") to remove revisions
	you don't care about.  This has its own problems, such as leaving
	dangling Tags and confusing the "update" command.

	There is some feeling among manipulators of binary files that
	"admin -l" should be used to serialize access.	See 3C.8.

	An interesting use for "admin" came up while maintaining CVS
	itself.	 I import versions of CVS onto the Vendor branch of my
	copy of CVS, make changes to some files and ship the diffs
	(created by "cvs diff -c -r TO_BRIAN") off to Brian Berliner.
	After creating the diff, I retag ("cvs tag -F TO_BRIAN") the
	working directory, which is then ready to produce the next patch.

	I'll use "add.c" as an example (only because the name is short).

	When the next release came out, I discovered that the released
	"add.c" (version 1.1.1.3 on the Vendor branch) was exactly the
	same as my modified file (version 1.3).	 I didn't care about the
	changelog on versions 1.2 and 1.3 (or the evidence of having done
	the work), so I decided to revert the file to the state where it
	looked like I had not touched the file -- where I was just using
	the latest on the vendor branch after a sequence of imports.

	To do that, I removed all the revisions on the main branch, except
	for the original 1.1 from which the Vendor branch sprouts:

		cvs admin -o1.2: add.c

	Then I set the RCS "default branch" back to the Vendor branch, the
	way import would have created it:

		cvs admin -b1.1.1 add.c

	And I moved the "TO_BRIAN" Tag to the latest revision on the
	Vendor branch, since that is the base from which further patches
	would be created (if I made any):

		cvs admin -NTO_BRIAN:1.1.1.3 add.c

	Instead of 1.1.1.3, I could have used one of the "Release Tags"
	last applied by "import" (3rd through Nth arguments).

	Suggestion:  Practice on non-essential files.



 3B.4	What should I avoid when using "admin"?

	If you know exactly what you are doing, hack away.  But under
	normal circumstances:

	Never use "admin" to alter branches (using the '-b' option), which
	CVS takes very seriously.  If you change the default branch, CVS
	will not work as expected.  If you create new branches without
	using the "tag -b" command, you may not be able to treat them as
	CVS branches.

	See 3C.8 for a short discussion of how to use "admin -l" for
	serializing access to binary files.

	The "admin -o <file>" allows you to delete revisions, usually a
	bad idea.  You should commit a correction rather than back out a
	revision.  Outdating a revision is prone to all sorts of problems:

	1. Discarding data is always a bad idea.  Unless something in the
	   revision you just committed is a threat to your job or your
	   life, (like naming a function "<boss's name>_is_a_dweeb", or
	   including the combination to the local Mafioso's safe in a C
	   comment), just leave it there.  No one cares about simple
	   mistakes -- just commit a corrected revision.

	2. The time travel paradoxes you can cause by changing history
	   are not worth the trouble.  Even if CVS can't interfere with
	   your parents' introduction, it *can* log commits in at least
	   two ways (history and loginfo).  The reports now lie -- the
	   revision referred to in the logs no longer exists.

	3. If you used "import" to place <file> into CVS, outdating all
	   the revisions on the Main branch back to and including revision
	   1.2 (or worse, 1.1), will produce an invalid CVS file.

	   If the <file>,v file only contains revision 1.1 (and the
	   connected branch revision 1.1.1.1), then the default branch
	   must be set to the Vendor branch as it was when you first
	   imported the file.  Outdating back through 1.2 doesn't restore
	   the branch setting.	Despite the above admonition against it,
	   "admin -b" is the only way to recover:

		cvs admin -b1.1.1 <file>

	4. Although you can't outdate a physical (RCS) branch point
	   without removing the whole branch, you *can* outdate a revision
	   referred to by a magic branch tag.  If you do so, you will
	   invalidate the branch.

	5. If you "outdate" a tagged revision, you will invalidate all
	   uses of the <tag>, not just the one on <file>.  A tag is
	   supposed to be attached to a consistent set of files, usually a
	   set built as a unit.	 By discarding one of the files in the
	   set, you have destroyed the utility of the <tag>.  And it
	   leaves a dangling tag, which points to nothing.

	6. And even worse, if you commit a revision already tagged, you
	   will alter what the <tag> pointed to without using the "tag"
	   command.  For example, if revision 1.3 has <tag> attached to it
	   and you "outdate" the 1.3 revision, <tag> will point to a
	   nonexistent revision.  Although this is annoying, it is nowhere
	   near as much trouble as the problem that will occur when you
	   commit to this file again, recreating revision 1.3.	The old
	   tag will point to the new revision, a file that was not in
	   existence when the <tag> was applied.  And the discrepancy is
	   nearly undetectable.


	If you don't understand the above, you should not use the admin
	command at all.


 3B.5	How do I restrict the "admin" command?	The -i flag in the modules
	file can restrict commits.  What's the equivalent for "admin"?

	At this writing, to disable the "admin" command, you will have
	to change the program source code, recompile and reinstall.


 3B.6	I backed out a revision with "admin -o" and committed a
	replacement.  Why doesn't "update" retrieve the new revision?

	CVS is confused because the revision in the ./CVS/Entries file
	matches the latest revision in the Repository *and* the timestamp
	in the ./CVS/Entries file matches your working file.  CVS believes
	that your file is "up-to-date" and doesn't need to be updated.

	You can cause CVS to notice the change by "touch"ing the file.
	Unfortunately what CVS will tell you is that you have a "Modified"
	file.  If you then "commit" the file, you will bypass the
	normal CVS check for "up-to-date" and will probably commit the
	revision that was originally removed by "admin -o".

	Changing a file without changing the revision number confuses CVS
	no matter whether you did it by replacing the revision (using
	"admin -o" and "commit" or raw RCS commands) or by applying an
	editor directly to a Repository (",v") file.  Don't do it unless
	you are absolutely certain no one has the latest revision of the
	file checked out.

	The best solution to this is to institute a program of deterrent
	flogging of abusers of "admin -o".

	The "admin" command has other problems."  See 3B.4 above.


----------------
-- Section 3C --	"checkout", "co", "get"
----------------

 **** Questions:

 3C.1	What is "checkout" for?
 3C.2	What is the "module" that "checkout" takes on the command line?
 3C.3	Isn't a CVS "checkout" just a bunch of RCS checkouts?
 3C.4	What's the difference between "update" and "checkout"?
 3C.5	Why can't I check out a file from within my working directory?
 3C.6	How do I avoid dealing with those long relative pathnames?
 3C.7	Can I move a checked-out directory?  Does CVS remember where it
	was checked out?
 3C.8	How can I lock files while I'm working on them the way RCS does?
 3C.9	What is "checkout -s"?	How is it different from "checkout -c"?


 **** Answers:

 3C.1	What is "checkout" for?

	To acquire a copy of a module (or set of files) to work on.

	All work on files controlled by CVS starts with a "checkout".


 3C.2	What is the "module" that "checkout" takes on the command line?

	It is a name for a directory or a collection of files in the
	Repository.  It provides a compact name space and the ability to
	execute before and after helper functions based on definitions in
	the modules file.

	See 1D.11.


 3C.3	Isn't a CVS "checkout" just a bunch of RCS checkouts?

	Like much of CVS, a similar RCS concept is used to support a CVS
	function.  But a CVS checkout is *not* the same as an RCS
	checkout.

	Differences include:

	1. CVS does not lock the files.	 Others may access them at the
	   same time.

	2. CVS works best when you provide a name for a collection of
	   files (a module or a directory) rather than an explicit list of
	   files to work on.

	3. CVS remembers what revisions you checked out and what branch
	   you are on, simplifying later commands.


 3C.4	What's the difference between "update" and "checkout"?

	The "checkout" and "update" commands are nearly equivalent in how
	they treat individual files.  They differ in the following ways:

	1. The "checkout" command always creates a directory, moves into
	   it, then becomes equivalent to "update -d".

	2. The "update" command does not create directories unless you add
	   the '-d' option.

	3. "Update" is intended to be executed within a working directory
	   created by "checkout".  It doesn't take a module or directory
	   argument, but figures out what Repository files to look at by
	   reading the files in the ./CVS administrative directory.

	4. The two commands generate completely different types of records
	   in the "history" file.


 3C.5	Why can't I check out a file from within my working directory?

	Though you *can* check out a file, you normally check out a module
	or directory.  And you normally do it only once at the beginning
	of a project.

	After the initial "checkout", you can use the "update" command
	to retrieve any file you want within the checked-out directory.
	There is no need for further "checkout" commands.

	If you want to retrieve another module or directory to work on,
	you must provide two pathnames: where to find it in the Repository
	and where to put it on disk.  The "modules" file and your current
	directory supply two pieces of naming information.  While inside a
	checked-out working directory, the CVS administrative information
	provides most of the rest.

	You should be careful not to confuse CVS with RCS and use
	"checkout" in the RCS sense.  An RCS "checkout" (which is
	performed by the RCS "co" command) is closer to a "cvs update"
	than to a "cvs checkout".


 3C.6	How do I avoid dealing with those long relative pathnames?

	This question has also been phrased:

	    How do I avoid all those layers of directories on checkout?
	or
	    Why do I have to go to the top of my working directory and
	    checkout some long pathname to get a file or two?


	This type of question occurs only among groups of people who
	decide not to use "modules".  The answer is to use "modules".

	When you hand the "checkout" command a relative pathname rather
	than a module name, all directories in the path are created,
	maintaining the same directory hierarchy as in the Repository.
	The same kind of environment results if you specify a "module"
	that is really an alias expanding into a list of relative
	pathnames rather than a list of module names.

	If you use "module" names, "checkout" creates a single
	directory by the name of the module in your current directory.
	This "module" directory becomes your working directory.

	The "module" concept combines the ability to "name" a collection
	of files with the ability to structure the Repository so that
	consistent sets of files are checked out together.  It is the
	responsibility of the Repository Administrators to set up a
	modules file that describes the software within the Repository.


 3C.7	Can I move a checked-out directory?  Does CVS remember where it
	was checked out?

	Yes and Yes.

	The ./CVS/Repository file in each working directory contains a
	pathname pointing to the matching directory within the
	Repository.  The pathname is either absolute or relative to
	$CVSROOT, depending on how you configured CVS.

	When you move a checked-out directory, the CVS administrative
	files will move along with it.	As long as you don't move the
	Repository itself, or alter your $CVSROOT variable, the moved
	directory will continue to be usable.

	CVS remembers where you checked out the directory in the
	"history" file, which can be edited, or even ignored if you
	don't use the "working directory" information displayed by the
	"history" command.


 3C.8	How can I lock files while I'm working on them the way RCS does?

	Until the day arrives of the all-powerful merge tool, there are
	still files that must be accessed serially.  For those instances,
	here's a potential solution:

	1. Install a pre-commit program in the "commitinfo" file to check
	   for RCS locks.  The program "rcslock.pl" performs this
	   function.  It can be found in the contrib directory of the CVS
	   source distribution.

	2. When you want to make a change to a file you know can't be
	   merged, first use "cvs admin -l" to lock the file.  If you
	   can't acquire the lock, use the standard "locked out" protocol:
	   go talk to the person holding the lock.

	3. Make sure the pre-commit program prints a message and exits
	   with a non-zero status if someone besides the user running
	   "commit" has the file locked.  This non-zero exist status will
	   cause the "commit" to fail cleanly.

	4. Make sure the pre-commit program exits with a zero status if
	   the file is either unlocked or locked by the user running
	   "commit".  The "cvs commit" command that kicked off the
	   pre-commit program will take a zero exist status as an OK and
	   checkin the file, which has the side-effect of unlocking it.


	===> The following is opinion and context.  Don't read it if you
	     are looking for a quick fix.

	The topic of locking CVS files resurfaces on the network every so
	often, producing the same results each time:

	The Big Endians:

	   CVS was designed to avoid locks, using a copy-modify-merge
	   model.  Locking is not necessary and you should take the time
	   to learn the CVS model which many people find workable.  So why
	   not get with the program and learn how to think the CVS way?

	The Little Endians:

	   The users determine how a tool is to be used, not the
	   designers.  We, the users, have always used locking, our bosses
	   demand locking, locking is good, locking is God.  I don't want
	   to hear any more lectures on the CVS model.	Make locking work.

	Any organization making active changes to a source base will
	eventually face the need to do parallel development.  Parallel
	development implies merges.  (If you plan to keep separate copies
	of everything and never merge, good luck.  Tell me who you work
	for so I can buy stock in your disk suppliers this year and sell
	your stock short next year.)

	Merges will never go away.  CVS chose to make "merges" stand
	front and center as an important, common occurrence in
	development.  It is one way of looking at things.

	For free-format text, the merge paradigm gives you a considerable
	amount of freedom.  It does take a bit of management, but any
	project should be ready to deal with it.

	On the other hand, there are many files that can't be merged using
	text merge techniques.	Straight text merge programs like "diff3"
	are guaranteed to fail on executables (with relative branch
	statements), files with self-referential counts stored in the file
	(such as TAGS files), or files with relative motion statements in
	them (such as Frame MIF files, many postscript files).	They
	aren't all binary files.

	For these types of files, and many others, there are only two
	solutions:

	1. Complex merge tools that are intimately aware of the contents
	   of the files to be merged.  (ClearCase, and probably others,
	   allow you to define your own "files types" with associated
	   "merge tools".)

	2. Serialization of access to the file.	 The only technical
	   solution to the problem of serialization is "locking".


	Since you can call a program that offers:

		 "Which one do you want? A/B?"

	a "merge tool", more and more merge tools will appear which can be
	hooked into a merge-intensive program like CVS.	 Think of a bitmap
	"merge" tool that displays the bitmaps on the screen and offers a
	"paint" interface to allow you to cut and paste, overlay, invert
	or fuse the two images such that the result is a "merged" file.

	My conclusion is that the need for locking is temporary, awaiting
	better technology.  For large development groups, locking is not
	an alternative to merging for text files.


 3C.9	What is "checkout -s"?	How is it different from "checkout -c"?

	The '-c' and '-s' options to "checkout" both cause the modules
	file to appear on standard output, but formatted differently.

	"checkout -c" lists the modules file alphabetized by the module
	name.  It also prints all data (including options like '-a' and
	"-o <prog>") specified in the modules file.

	"checkout -s" lists the modules file sorted by "status" field,
	then by module name.  The status field was intended to allow you
	to mark modules with strings of your choice to get a quick sorted
	report based on the data you chose to put in the status fields.	 I
	have used it for priority ("Showstopper", etc as tied into a bug
	database), for porting status ("Ported", "Compiled", etc.  when
	porting a large collection of modules), for "assignee" (the person
	responsible for maintenance), and for "test suite" (which
	automatic test procedure to run for a particular module).


----------------
-- Section 3D --	"commit", "ci", "com"
----------------

 **** Questions:

 3D.1	What is "commit" for?
 3D.2	If I edit ten files, do I have to type "commit" ten times?
 3D.3	Explain: cvs commit: Up-to-date check failed for `<file>'
 3D.4	What happens if two people try to "commit" conflicting changes?
 3D.5	I committed something and I don't like it.  How do I remove it?
 3D.6	Explain: cvs commit: sticky tag `V3' for file `X' is not a branch
 3D.7	Why does "commit -r <tag/rev>" put newly added files in the Attic?
 3D.8	Why would a "commit" of a newly added file not produce rev 1.1?


 **** Answers:

 3D.1	What is "commit" for?

	To store new revisions in the Repository, making them visible
	to other users.


 3D.2	If I edit ten files, do I have to type "commit" ten times?

	No.  The "commit" command will take multiple filenames, directory
	names and relative pathnames on the command line and commit them
	all with the same log message.	If a file is unchanged, even if it
	is explicitly listed on the command line, CVS will skip it.

	Like all CVS commands, "commit" will work on the whole directory
	by default.  Just type "cvs commit" to tell CVS to commit all
	modified files (i.e. the files that "update" would display
	preceded by 'M') in the current directory and in all
	sub-directories.


 3D.3	Explain: cvs commit: Up-to-date check failed for `<file>'

	You may not "commit" a file if your BASE revision (i.e. the
	revision you last checked out, committed or retrieved via
	"update") doesn't match the HEAD revision (i.e the latest revision
	on your branch, usually the Main Branch).

	In other words, someone committed a revision since you last
	executed "checkout", "update" or "commit".  You must now execute
	"update" to merge the other person's changes into your working
	file before "commit" will work.	 You are thus protected (somewhat)
	from a common form of race condition in source control systems,
	where a checkin of a minor alteration of a second copy of the same
	base file obliterates the changes made in the first.

	Normally, the "update" command's auto-merge should be followed
	by another round of building and testing before the "commit".


 3D.4	What happens if two people try to "commit" conflicting changes?

	Conflicts can occur only when two developers check out the same
	revision of the same file and make changes.  The first developer
	to commit the file has no chance of seeing the conflict.  Only the
	second developer runs into it, usually when faced with the
	"Up-to-date" error explained in the previous question.

	There are two types of conflicts:

	1. When two developers make changes to the same section of code,
	   the auto-merge caused by "update" will print a 'C' on your
	   terminal and leave "overlap" markers in the file.

	   You are expected to examine and clean them up before committing
	   the file.  (That may be obvious to *some* of you, but . . .)

	2. A more difficult problem arises when two developers change
	   different sections of code, but make calls to, or somehow
	   depend on, the old version of each other's code.

	   The auto-merge does the "right" thing, if you view the file
	   as a series of text lines.  But as a program, the two
	   developers have created a problem for themselves.

	   This is no different from making cross-referential changes in
	   *separate* files.  CVS can't help you.  In a perfect world, you
	   would each refer to the specification and resolve it
	   independently.  In the real world you have to talk/argue, read
	   code, test and debug until the combined changes work again.

	Welcome to the world of parallel development.


 3D.5	I committed something and I don't like it.  How do I remove it?

	Though you *can* use the "admin -o" (synonym: "rcs -o") command to
	delete revisions, unless the file you committed is so embarrassing
	that the need to eradicate it overrides the need to be careful,
	you should just grab an old version of the file ("update -p -r
	<previous-rev>" might help here) and commit it on top of the
	offending revision.

	See Section 3B on "admin".


 3D.6	Explain: cvs commit: sticky tag `V3' for file `X' is not a branch

	The message implies two things:

	     1. You created your working directory by using "checkout -r
		V3", or you recently executed "update -r V3".

	     2. The tag named V3 is not a branch tag.


	CVS records (i.e. makes "sticky") any "-r <tag/rev>" argument
	handed to the "checkout" or "update" commands.	The <tag/rev> is
	recorded as the CVS working branch, which is the branch to which
	"commit" will add a new revision.

	Branch tags are created when you use the -b switch on the "tag" or
	"rtag" commands.  Branch tags are magic tags that don't create a
	physical branch, but merely mark the revision to branch from when
	the branch is needed.  The first commit to a magic branch creates
	a physical branch in the RCS files.

	You can commit onto the end of the Main Trunk, if you have no
	sticky tag at all, or onto the end of a branch, if you have a
	sticky branch tag.  But you can't commit a file that has a sticky
	tag not pointing to a branch.  CVS assumes a sticky Tag or
	Revision that does not refer to a branch is attached to the middle
	of a series of revisions.  You can't squeeze a new revision
	between two others.  Sticky dates also block commits since they
	never refer to a branch.


	Scenario1:

	    If you don't want a branch and were just looking at an old
	    revision, then you can move back to the Main Branch by typing:

		cvs update -A {files or dirs, default is '.'}

	    or you can move to the branch named <branch_tag> by:

		cvs update -r <branch_tag> {files or dirs, default is '.'}


	Scenario2:

	    If you really wanted to be on a branch and made an earlier
	    mistake by tagging your branch point with a non-branch tag,
	    you can recover by adding a new branch tag to the old
	    non-branch tag:

		    cvs rtag -b -r <oldtag> <newtag> <module>

	    (It was not a big mistake.	Branch-point tags can be useful.
	     But the <newtag> must have a different name.)

	    If you don't know the <module> name or don't use "modules",
	    you can also use "tag" this way:

		    cvs update -r <oldtag>
		    cvs tag -b <newtag> .

	    Then, to put your working directory onto the branch, you type:

		    cvs update -r <newtag>


	    You can't delete <oldtag> before adding <newtag>, and I would
	    not advise deleting the <oldtag> at all, because it is useful
	    in referring to the branch point.  If you must, you can delete
	    the non-branch tag by:

		    cvs rtag -d <oldtag> <module>
		or
		    cvs tag -d <oldtag> .


	Scenario3:

	    If you made the same mistake as in Scenario2 (of placing a
	    non-branch tag where you wanted a branch tag), but really want
	    <oldtag> to be the name of your branch, you can execute a
	    slightly different series of commands to rename it and move
	    your working directory onto the branch.

	    Warning: This is not a way to rename a branch tag.	It is a way
		     to turn a non-branch tag into a branch tag with the
		     same name.

		    cvs rtag -r <oldtag> <branch_point_tag> <module>
		    cvs rtag -d <oldtag> <module>
		    cvs rtag -b -r <branch_point_tag> <oldtag> <module>

	    Then, if you really must, delete the <branch_point_tag>:

		    cvs rtag -d <branch_point_tag> <module>



	Note:	The unwieldy mixture of "tag" and "rtag" is mostly
		because you can't specify a revision (-r <tag>) to the
		"tag" command.

	See 4C.3 for more info on creating a branch.


 3D.7	Why does "commit -r <tag/rev>" put newly added files in the Attic?

	If you specify "-r <rev>" (where <rev> is a dotted numeric number
	like 2.4), it correctly sets the initial revision to <rev>, but it
	also attaches the numeric <rev> as a sticky tag and throws the
	file into the Attic.  This is a bug.  The obvious solution is to
	move the file out of the Attic into the associated Repository
	directory and "update -A" the file.  There are no Tags to clean up.

	If you specify "-r <tag>" to commit a newly added file, the <tag>
	is treated like a <branch_tag>, which becomes a symbolic RCS label
	pointing to the string '1', which can be considered to be the
	"Main branch number" when the main branch is still at revision
	1.N.  The file is also thrown into the Attic.  See 4C.8 for a way
	to recover from this.

	In fact, a plain "commit" without the "-r" will throw a newly
	added file into the Attic if you added it to a directory checked
	out on a branch.  See 3A.[2-5].

	See Section 4C, on Branching, for many more details.


 3D.8	Why would a "commit" of a newly added file not produce rev 1.1?

	When committing a newly added file CVS looks for the highest main
	branch major number in all files in the ./CVS/Entries file.
	Normally it is '1', but if you have a file of revision 3.27 in
	your directory, CVS will find the '3' and create revision 3.1 for
	the first rev of <file>.  Normally, the first revision is 1.1.


----------------
-- Section 3E --	"diff", "di", "dif"
----------------

 **** Questions:

 3E.1	What is "diff" for?
 3E.2	Why did "diff" display nothing when I know there are later
	committed revisions in the Repository?
 3E.3	How do I display what changed in the Repository since I last
	executed "checkout", "update" or "commit"?
 3E.4	How do I display the difference between my working file and what
	I checked in last Thursday?
 3E.5	Why can't I pass long options, like --unified, to "diff"?


 **** Answers:

 3E.1	What is "diff" for?

	1. To display the difference between a working file and its BASE
	   revision (the revision last checked out, updated or committed):

		cvs diff <file>

	2. To display the difference between a working file and a
	   committed revision of the same file:

		cvs diff -r <tag/rev> <file>

	3. To display the difference between two committed revisions of
	   the same file:

		cvs diff -r <tag1/rev1> -r <tag2/rev2> <file>

	You can specify any number of <file> arguments.	 Without any
	<file> arguments, it compares the whole directory.

	In the examples above, "-D <date>" may be substituted wherever
	"-r <tag/rev>" appears.	 The revision a <date> refers to is the
	revision that existed on that date.


 3E.2	Why did "diff" display nothing when I know there are later
	committed revisions in the Repository?

	By default, "diff" displays the difference between your working
	file and the BASE revision.  If you haven't made any changes to
	the file since your last "checkout", "update" or "commit" there is
	no difference to display.

	To display the difference between your working file and the latest
	revision committed to your current branch, type:

		cvs diff -r HEAD <file>


 3E.3	How do I display what changed in the Repository since I last
	executed "checkout", "update" or "commit"?

	A special tag (interpreted by CVS -- it does not appear in the Tag
	list) named "BASE" always refers to the revision you last checked
	out, updated or committed.  Another special tag named "HEAD"
	always refers to the latest revision on your working branch.

	To compare BASE and HEAD, you type:

		cvs diff -r BASE -r HEAD <file>


 3E.4	How do I display the difference between my working file and what
	I checked in last Thursday?

		cvs diff -D "last Thursday" <file>

	where "last Thursday" is a date string.	 To be more precise, the
	argument to the '-D' option is a timestamp.  Many formats are
	accepted.  See the man page under "-D date_spec" for details.


 3E.5	Why can't I pass long options, like --unified, to "diff"?

	CVS only handles single character '-X' arguments, not the FSF long
	options.  CVS also passes through only arguments it knows about,
	because a few arguments are captured and interpreted by CVS.

	If you didn't configure RCS and CVS to use the GNU version of
	diff, long options wouldn't work even if future versions of CVS
	acquire the ability to pass them through.

	Most of the long options have equivalent single-character options,
	which do work.	The "--unified" option is equivalent to '-u' in
	revisions of GNU diff since 1.15.



----------------
-- Section 3F --	"export", "exp", "ex"
----------------

 **** Questions:

 3F.1	What is "export" for?
 3F.2	Why does it remove the RCS keywords so I can't use the "ident"
	command on the source files?
 3F.3	Can I override the '-kv' flag CVS passes to RCS?
 3F.4	Why doesn't "export" have a '-k' flag like "import" does?
 3F.5	Why does "export -D" check out every file in the Attic?


 **** Answers:

 3F.1	What is "export" for?

	"export" checks out a copy of a module in a form intended for
	export outside the CVS environment.  The "export" command produces
	the same directory and file structure as the "checkout" command,
	but it doesn't create "CVS" sub-directories and it removes all the
	RCS keywords from the files.


 3F.2	Why does it remove the RCS keywords so I can't use the "ident"
	command on the source files?

	It removes the RCS keywords, so that if the recipient of the
	exported sources checks them into another set of RCS files (with
	or without CVS), and then makes modifications through RCS or CVS
	commands, the revision numbers that they had when you exported
	them will be preserved.	 (That ident no longer works is just an
	unfortunate side effect.)

	The theory is that you are exporting the sources to someone else
	who will make independent changes, and at some point you or they
	will want to know what revisions from your Repository they started
	with (probably to merge changes, or to try to decide whether to
	merge changes).

	A better way to handle this situation would be to give them their
	own branch of your Repository.	They would need to remember to
	checkin the exported sources with RCS IDs intact (ci -k) so that
	their changes would get revision numbers from the branch, rather
	than starting at 1.1 again.  Perhaps a future version of CVS will
	provide a way to export sources this way.

				Contributed by Dan Franklin


 3F.3	Can I override the '-kv' flag CVS passes to RCS?

	Not as of CVS version 1.4.


 3F.4	Why doesn't "export" have a '-k' flag like "import" does?

	Export is intended for a specific purpose -- to remove all trace
	of revision control on the way *out* of CVS.


 3F.5	Why does "export -D" check out every file in the Attic?

	See 5B.3 for an explanation of the same problem with "update".



----------------
-- Section 3G --	"history", "hi", "his"
----------------

 **** Questions:

 3G.1	What is "history" for?
 3G.2	Of what use is it?
 3G.3	What is this, Big Brother?
 3G.4	I deleted my working directory and "history" still says I have
	it checked out.	 How do I fix it?
 3G.5	So I *can* edit the History file?
 3G.6	Why does the history file grow so quickly?
 3G.7	What is the difference between "cvs history -r <tag/rev>" and
	"cvs history -t <tag>"?
 3G.8	Why does "cvs history -c -t <tag>" fail to print anything?
 3G.9	"cvs history -a -o" only printed one line for each checked-out
	module.	 Shouldn't it print all the directories where the
	modules are checked out?
 3G.10	I can't figure out "history", can you give me concrete examples?
 3G.11	Can we merge history files when we merge Repositories?


 **** Answers:

 3G.1	What is "history" for?

	To provide information difficult or impossible to extract out of
	the RCS files, such as a "tag" history or a summary of module
	activities.


 3G.2	Of what use is it?

	I have found it useful in a number of ways, including:

	1. Providing a list of files changed since

	   - A tagged release.
	   - Yesterday, last Thursday, or a specific date.
	   - Someone changed a specific file.

	2. Providing a list of special events:

	   - Files added or removed since one of the above events.
	   - Merge failures since one of the above events.  (Where did the
	     conflicts occur?)
	   - Has anyone (and who) grabbed the revision of this file I
	     committed last week, or are they still working blind?

	3. Telling me how often a file/directory/module has been changed.

	4. Dumping a summary of work done on a particular module,
	   including who last worked on it and what changed.

	5. Displaying the checked-out modules and where they are being
	   worked on.

	6. To tell me what users "joe" and "malcolm" have done this week.


 3G.3	What is this, Big Brother?

		War is Peace.
		Freedom is Slavery.
		Ignorance is Strength.

	Normally manager types and those with the power to play Big
	Brother don't care about this information.  The Software Engineer
	responsible for integration usually wants to know who is working
	on what and what changed.  Use your imagination.


 3G.4	I deleted my working directory and "history" still says I have
	it checked out.	 How do I fix it?

	You can use "release -f" to forcibly add a "release" record to the
	history file for a working directory associated with a "module".
	If your version of "release" doesn't have the '-f' option, or you
	checked out the directory using a relative path, you have to edit
	the $CVSROOT/CVSROOT/history file.

	You can remove the last 'O' line in the history file referring
	to the module in question or add an 'F' record.


 3G.5	So I *can* edit the History file?

	Yes, but if you are using history at all, you should take a little
	care not to lose information.  I normally use Emacs on the file,
	since it can detect that a file has changed out from under it.
	You could also copy and zero out the history file, edit the copy
	and append any new records to the edited copy before replacing it.


 3G.6	Why does the history file grow so quickly?

	It stores 'U' records, which come in handy sometimes when you
	are tracking whether people have updated each other's code
	before testing.	 There should (and probably will sometime) be a
	way to choose what kinds of events go into the history file.

	The contributed "cln_hist.pl" script will remove all the 'U'
	records, plus matching pairs of 'O' and 'F' records during
	your normal clean up of the history file.


 3G.7	What is the difference between "cvs history -r <tag/rev>" and
	"cvs history -t <tag>"?

	The '-t' option looks for a Tag record stored by "rtag" in the
	history file and limits the search to dates after the last <tag>
	of the given name was added.

	The '-r' option was intended to search all files looking for the
	<tag> in the RCS files.	 It takes forever and needs to be
	rewritten.


 3G.8	Why does "cvs history -c -t <tag>" fail to print anything?

	You have been using "tag" instead of "rtag".  The "tag" command
	currently doesn't store a history record.  This is another remnant
	of CVS's earlier firm belief in "modules".  But it also has a
	basis in how "rtag" and "tag" were originally used.

	"rtag" was intended for large-scale tagging of large chunks of the
	Repository, an event work recording.  "tag" was intended for
	adding and updating tags on a few files or directories, though it
	could also be used to tag the entire checked-out working tree when
	there is no module defined to match the tree or when the working
	tree is the only place where the right collection of revisions to
	tag can be found.


 3G.9	"cvs history -a -o" only printed one line for each checked-out
	module.	 Shouldn't it print all the directories where the
	modules are checked out?

	Not as designed.

	Command			Question it is supposed to answer.
	----------------	------------------------------------------
	cvs history -o		What modules do I have checked out?
	cvs history -a -o	<same for all users>

	cvs history -o -w	What working directories have I created
				and what modules are in them?
	cvs history -a -o -w	<same for every user>

	The -o option chooses the "checked out modules" report, which is
	the default history report.


 3G.10	I can't figure out "history", can you give me concrete examples?

	Default output selects records only for the user who executes the
	"history" command.  To see records for other users, add one or
	more "-u user" options or the '-a' option to select *all* users.

	To list (for the selected users):	Type "cvs history" and:

	* Checked out modules:			-o    (the default)
	* Files added since creation:		-x A
	* Modified files since creation:	-c
	* Modified files since last Friday:	-c -D 'last Friday'
	* Modified files since TAG was added:	-c -t <tag>
	* Modified files since TAG on files:	-c -r <tag>
	* Last modifier of file/Repository X?	-c -l -[fp] X
	* Modified files since string "str":	-c -b str
	* Tag history:	(Actually "rtag".)	-T
	* History of file/Repository/module X:	-[fpn] X
	* Module report on "module":		-m module


 3G.11	Can we merge history files when we merge Repositories?

	Assuming that the two Repositories have different sets of
	pathnames, it should be possible to merge two history files by
	sorting them together by the timestamp fields.

	You should be able to run:

	    sort +0.1 ${dir1}/history ${dir2}/history > history


	If you "diff" a standard history file before and after such a
	sort, you might see other differences caused by garbage (split
	lines, nulls, etc) in the file.	 If your Repository is mounted
	through NFS onto multiple machines you will also see a few
	differences caused by different clocks on different machines.
	(Especially if you don't use NTP to keep the clocks in sync.)



----------------
-- Section 3H --	"import", "im", "imp"
----------------

 **** Questions:

 3H.1	What is "import" for?
 3H.2	How am I supposed to use "import"?
 3H.3	Why does import put files on a branch?	Why can't I work on the
	main trunk instead of a Vendor branch?
 3H.4	Is there any way to import binary files?
 3H.5	Why does "import" corrupt some binary files?
 3H.6	How do I retain the original $\Revision$ strings in the sources?
=3H.7	I imported some files for the Yarg compiler that compiles files
	with a suffix of ".yarg" and whose comment prefix is "YARG> ".
	When I check them out, they will no longer compile because they
	have this junk in them.	 Why?
 3H.8	How do I make "import" save the timestamps on the original files?
 3H.9	Why can't I "import" 3 releases on different branches?
 3H.10	What do I do if the Vendor adds or deletes files between releases?
 3H.11	What about if the Vendor changes the names of files or
	directories, or rearranges the whole structure between releases?
 3H.12	I thought "import" was for Vendor releases, why would I use it
	for code of my own?  Do I have to use import?
 3H.13	How do I import a large Vendor release?
 3H.14	Explain: ERROR: cannot create link to <file>: Permission denied
 3H.15	Where does the -m <message> go when the file doesn't change?
 3H.16	How do I "import" just the files ignored by a previous "import"?
 3H.17	Why did "import" ignore all the symlinks?


 **** Answers:

 3H.1	What is "import" for?

	The "import" command is a fast way to insert a whole tree of files
	into CVS.

	The first "import" to a particular file within the Repository
	creates an RCS file with a single revision on the "Vendor branch."
	Subsequent "import"s of the same file within the Repository append
	a new revision onto the Vendor branch.	It does not, as some seem
	to believe, create a new branch for each "import".  All "imports"
	are appended to the single Vendor branch.

	If the file hasn't changed, no new revision is created -- the new
	"Release-Tag" is added to the previous revision.

	After the import is finished, files you have not changed locally
	are considered to have changed in the "Main line of development".
	Files you *have* changed locally must have the new Vendor code
	merged into them before they are visible on the "Main line".

		See 4C.6 and 4C.15


 3H.2	How am I supposed to use "import"?

	Create a source directory containing only the files you want to
	import.	 Make sure you clean up any cruft left over from previous
	builds or editing.  You want to make sure that the directory
	contains only what you want to call "source" from which everything
	else is built.

	If this is not the first import from this "Vendor", you should
	also compare the output of "find . ! -name CVS -print | sort"
	executed both at the head of a checked out working directory and
	at the head of the sources to be imported.  If you find any
	deleted or renamed files, you have to deal with them by hand.
	(See 4B.8 on renaming.)

	"cd" into your source directory and type:

	    cvs import -m "Message" <repos> <Vendor-Tag> <Release-Tag>

	where <repos> is the relative directory pathname within the
	Repository that corresponds to the sources you are importing.

	You might also consider using the "-I !" option to avoid ignoring
	anything.  It is easier to remove bogus files from the Repository
	than to create a sparse tree of the ignored files and rerun
	"import".

	For example, if the FSF, CVS, Make and I are still active in the
	year 2015, I'll import version 89.53 of GNU make this way:

	    cvs import -m "GNUmake V89.53" gnu/make GNU GNUMAKE_89_53

	See 3H.13 for more details.


 3H.3	Why does import put files on a branch?	Why can't I work on the
	main trunk instead of a Vendor branch?

	This was a Design choice.  The Vendor branch is the way "import"
	deals with a Vendor release.  It is a solution to the Engineering
	problem of how to merge multiple external releases of
	Vendor-supplied sources into your ongoing work.	 The Vendor
	releases are kept on a separate, special, "Vendor" branch and your
	work is kept on the RCS trunk.	New Vendor releases are imported
	onto the Vendor branch and then merged into your work, if there is
	any, on the trunk.

	This way, you can use CVS to find out not only about your work,
	but you can also find out what the Vendor changed by diffing
	between two of the Release Tags you handed to "import".

	CVS was designed to work this way.  If you use CVS in some other
	way, you should think carefully about what you are doing.

	Note that the CVS "Main Branch" and the RCS Main Trunk are not the
	same.  Placing files on the Vendor Branch doesn't keep you from
	creating a development branch to work on.

	See Section 4C, on Branching.


	If you are not working with 3rd party (i.e. Vendor) sources, you
	can skip the "import" and avoid the Vendor branch entirely.  It
	works just as well to move pre-existing RCS files into Repository
	directories.

	You can create a whole Repository tree by copying a directory
	hierarchy of normal source files directly into the Repository and
	applying CVS to it.  Here's an idea you should *test* before using:

		cd <your source tree>
		set source = `pwd`
		set module = xyzzy	<<== Your choice of directory name
		mkdir $CVSROOT/$module
		cd $CVSROOT/$module
		(cd $source; tar cf - .) | tar xvpBf -
		find . -type f -exec ci -t-Original. {} \;

	The RCS "ci" command, without -u or -l options, will turn your
	source file into an RCS (",v") and delete the original source.


 3H.4	Is there any way to import binary files?

	If you configured CVS to use the GNU version of "diff" and
	"diff3", then you can import any kind of file.

	Binary files with RCS keywords in them are a problem, since you
	don't want them to expand.

	If the tree you are about to "import" is entirely filled with
	binary files, you can use the '-ko' option on "import".
	Otherwise, I would run the import normally, then fix the binary
	files as described below in 3H.5.

	See 4D.1 on Binary files.


 3H.5	Why does "import" corrupt some binary files?

	The RCS "co" command, when it is invoked by a CVS "checkout" or
	"update" (or after a "commit") command, searches for and expands a
	list of keywords within the file.  They are documented in the RCS
	"co" man page.	Strings such as "$\Id$" (or "$\Id:"), or
	"$\Revision$" (or "$\Revision:") are altered to the include the
	indicated information.

	[[Note: The keywords should appear in the text without the '\'
	  character I have inserted to *avoid* expansion here.	The only
	  real RCS keywords in this document are at the top of the file,
	  where I store the Revision and Date.]]

	If RCS keyword strings show up in a binary file, they will be
	altered unless you set the '-ko' option on the RCS files to tell
	RCS to keep the original keyword values and not to expand new
	ones.  After "import", you can set the '-ko' option this way:

		cvs admin -ko <file>
		rm <file>
		cvs update <file>

	After an import that didn't use '-ko' (because the whole tree
	wasn't of binary files) you should fix up the binary files as
	described above before checking out any new copies of the files
	and before updating any working directories you checked out
	earlier.

	See 4D.1 on Binary files.


 3H.6	How do I retain the original $\Revision$ strings in the sources?

	If you want to leave old RCS keywords as they are, you can use the
	'-ko' tricks described above.


=3H.7	I imported some files for the Yarg compiler that compiles files
	with a suffix of ".yarg" and whose comment prefix is "YARG> ".
	When I check them out, they will no longer compile because they
	have this junk in them.	 Why?

	YARG>YARG>YARG>YARG>YARG>YARG>YARG>YARG>YARG>YARG>YARG>YARG>YARG>
	YARG> $\Log:
	# Revision 1.3	1998/03/03  00:16:16  bubba
	# What is 2+2 anyway?
	#
	# Revision 1.2	1998/03/03  00:15:15  bubba
	# Added scorekeeping.
	YARG>
	YARG>YARG>YARG>YARG>YARG>YARG>YARG>YARG>YARG>YARG>YARG>YARG>YARG>


	Well bubba, "Yarg" hasn't hit the big time yet.	 Neither RCS nor
	CVS know about your suffix or your comment prefix.  So you have
	two choices:

	1. Check out the Yarg-less module, and tell all the files about
	   your comment prefix.	 Visit each directory and type:

		cvs admin -c"YARG> " *.yarg

	   If *all* files in the whole directory tree are Yarg files,
	   you can use this instead:

		cvs admin -c"YARG> " .

	   Then save any changes you made, remove all the "*.yarg" files
	   and grab new copies from the Repository:

		rm *.yarg
		  (or: find . -name '*.yarg' -exec rm {} ';')
		  (or: find . -name '*.yarg' -print | xargs rm)
		  (or: find . -name '*.yarg' -print0 | xargs -0 rm
		   if you have spaces in filenames and the GNU find/xargs.)
		cvs update

	   It might be faster to remove the whole directory and check it
	   out again.

	2. Change the import.c file in the CVS sources and add the .yarg
	   suffix, along with the "YARG> " comment prefix to the
	   "comtable" array.

	   If you ever plan to add new files with $\Log in them, you
	   should also go into the RCS sources and make the same change in
	   the table contained in the "rcsfnms.c" file.

	   Then delete the imported files from the Repository and
	   re-"import" the sources.


 3H.8	How do I make "import" save the timestamps on the original files?

	Use "import -d" to save the current timestamps on the files as the
	RCS revision times.

	See 4D.8 for another aspect of file timestamps.


 3H.9	Why can't I "import" 3 releases on different branches?

	I'll bet you typed something like this:

		cd /src/blasto.v2
		cvs import -b 1.1.2  VENDOR2 Version2
		cd /src/blasto.v3
		cvs import -b 1.1.3  VENDOR3 Version3
		cd /src/blasto.v4
		cvs import -b 1.1.4  VENDOR4 Version4

	This is wrong, or at least it won't help you much.  You have
	created three separate Vendor branches, which is probably not
	what you wanted.

	Earlier versions of CVS, as described in Brian Berliner's Usenix
	paper, tried to support multiple Vendor branches on the theory
	that you might receive source for the *same* program from multiple
	vendors.  It turns out that this is very rare, whereas the need to
	branch in *your* development, for releases and for project
	branches, is much greater.

	So the model now is to use a single vendor branch to contain a
	series of releases from the same vendor.  Your work moves along
	on the Main Trunk, or on a CVS branch to support a real
	"branch in development".

	To set this up, you should type this instead of the above:

		cd /src/blasto.v2
		cvs import VENDOR Version2
		cd /src/blasto.v3
		cvs import VENDOR Version3
		cd /src/blasto.v4
		cvs import VENDOR Version4


 3H.10	What do I do if the Vendor adds or deletes files between releases?

	Added files show up with no extra effort.  To handle "removed"
	files, you should always compare the tree structure of the new
	release against the one you have in your Repository.  If the
	Vendor has removed files since the previous release, go into a
	working directory containing your current version of the sources
	and "cvs remove" (followed by "cvs commit" to make it really take
	effect) each file that is no longer in the latest release.

	Using this scheme will allow you to "checkout" any version of
	the vendor's code, with the correct revisions and files, by
	using "checkout -r Version[234]".

	Renames are harder to find, since you have to compare file
	contents to determine that one has occurred.  If you notice one,
	see 4B.8 on renaming files.


 3H.11	What about if the Vendor changes the names of files or
	directories, or rearranges the whole structure between releases?

	Currently CVS can't handle this cleanly.  It requires
	"renaming" a bunch of files or directories.

	See 4B.8 on "renaming" for more details.

	What I generally do is to close the Repository for a while and
	make changes in both the Repository and in a copy of the vendor
	release until the structure matches, then execute the import.

	If you ever have to check out and build an old version, you may
	have to use the new, or completely different Makefiles.


 3H.12	I thought "import" was for Vendor releases, why would I use it
	for code of my own?  Do I have to use import?

	For code you produce yourself, "import" is a convenience for fast
	insertion of whole trees.  It is not necessary.	 You can just as
	easily create ",v" files using the RCS "ci" command and move
	them directly into the Repository.

	Other than the CVSROOT directory, the Repository consists entirely
	of directories of ",v" files.  The Repository contains no other
	state information.

	See Section 4B, on Setting up and Managing the Repository.


 3H.13	How do I import a large Vendor release?

	When the sum of the changes made by the Vendor and the changes
	made by local developers is small, "import" is not a big
	problem.  But when you are managing a large Repository, any care
	taken up front will save you time later.

	First read the following, then, before executing "import", see the
	questions in Section 4C dealing with branch merges and Vendor
	branch merges.

	0. If this is not the first import of this code, before starting,
	   rtag the whole directory you will be changing.

	1. The first step is to make sure the structure of the new files
	   matches the structure of the current Repository.

	   Run "find . -print | sort" on both trees and "diff" the output.

	2. Alter the "source" tree until the "diff" (of the list of
	   filenames, not of the whole trees) shows that the directory
	   structures are equivalent.

	   The "comm" command, if you have it, can help figure out what
	   has been added or deleted between releases.

	3. If they deleted any files, you can handle them cleanly with
	   "cvs remove".  The command "comm -23 files.old files.new" will
	   show you a list of files that need to be removed.

	   You should examine the list first to see if any have been
	   renamed rather than simply deleted.

	4. If they renamed any files, see 4B.8 on renaming files.

	5. Remember to *SAVE* the output from the import command.

	6. When you have dealt with removed and renamed files, then you
	   can execute the import:

	   cd <new source>
	   cvs import -I ! -m "Message" <repos> <VendorTag> <ReleaseTag>


	   Where

	   "-I !"	is an optional argument that keeps "import" from
			ignoring files.	 The comparison of the "find"
			commands above will probably avoid the need for
			this, but it is easier to remove files from the
			Repository than to run a subset "import" to catch
			just the ignored files.
			[You might have to quote or backwhack the '!'.]

	   Message	is the log message to be stored in the RCS files.

	   <repos>	is a relative path to a directory within the
			Repository.  The directory <new source> must be at
			the same relative level within the new sources as
			the <repos> you give is within the Repository.	(I
			realize this is not obvious.  Experiment first.)

	   <VendorTag>	is a Tag used to identify the Vendor who sent you
			the files you are importing.  All "imports" into
			the same <repos> *must* use the same VendorTag.
			You can find it later by using the "log" command.

	   <ReleaseTag> is a Tag used to identify the particular release
			of the software you are importing.  It must be
			unique and should be mnemonic -- at least include
			the revision number in it.  (Note: you can't use
			'.' characters in a Tag.  Substitute '_' or '-'.)

	7. There will be six categories of files to deal with.
	   (Actually there are eight, but you have already dealt with
	   "removed" and "renamed" files.)

	   If this is the first "import" into a given <repos> directory,
	   only the first three of these ('I', 'L' and 'N') can occur.


	   a. Ignored file.

		CVS prints:	I filename

		You'll need to examine it to see if it *should* have been
		ignored.  If you use "-I !", nothing will be ignored.


	   b. Symbolic link.

		CVS prints:	L linkname

		Links are "ignored", but you'll probably want to create
		a "checkout helper" function to regenerate them.


	   c. New file.

		CVS prints:	N filename

		CVS creates a new file in the Repository.  You don't
		have to do anything to the file, but you might have to
		change Makefiles to refer to it if this is really a new
		file.


	   d. A file unchanged by the Vendor since its last release.

		CVS prints:	U filename

		CVS will notice this and simply add the new ReleaseTag
		to the latest rev on the Vendor branch.

		No work will be needed by you, whether you have changed
		the file or not.  No one will notice anything.

	   e. A file changed by the Vendor, but not by you.

		CVS prints:	U filename

		CVS should add the file onto the vendor branch and
		attach the Release Tag to it.

		When you next execute "update" in any working directory
		you'll get the new revision.


	   f. A file changed by both the Vendor and by you.

		CVS prints:	C filename

		These are the trouble files.  For each of these files
		(or in groups -- I usually do one directory at a
		time), you must execute:

		    cvs update -j <PreviousReleaseTag> -j <ReleaseTag>
		or
		    cvs update -j <VendorTag:yesterday> -j <VendorTag>

		It will print either 'M' (if no overlaps) or 'C', if
		overlaps.  If a 'C' shows up, you'll need to edit the
		file by hand.

		Then, for every file, you'll need to execute "cvs commit".

		See the part of Section 4C dealing with branch merges.


	8. If you are truly performing a large import, you will most
	   likely need help.  Managing those people is another problem
	   area.

	   Since the merge of the Vendor branch is just like any other
	   merge, you should read section 4C for more info about
	   performing and cleaning up merges.

	   The larger the import, and the larger the group of people
	   involved, the more often you should use "tag" and "rtag" to
	   record even trivial milestones.  See 4C.14, especially the
	   "paranoid" section.

	   Before starting the import, you should install and test a
	   "commitinfo" procedure to record all commits in a file or via
	   Email to a mail archive.  Along with the tags you placed on the
	   Repository before the import, this archive will help to track
	   what was changed, if problems occur

	   There are four stages to the recovery:

	   A. Parcel out the work -- Effective Emacs Engineering.

	      As input to the assignment process, you might want to
	      examine the tree and record the last person who changed the
	      file.  You can also research, if you don't already know, who
	      is expert in each area of the software.

	      Examine the import log (you saved the output, right?),
	      estimate how much work is involved in each area and assign
	      groups of files to individual developers.	 Unless some
	      directory is immense, it is easier to manage if you assign
	      whole directories to one person.

	      Keep a list.  Suggest a completion date/time.  Tell them to
	      "commit" the file when they are finished with the merge.
	      If you tagged the Repository before starting the import, you
	      should have no trouble figuring out what happened.

	      If you can, find out (or tell them) which working directory
	      to use.  You should verify that the working directory they
	      use is on the Main Branch ("update -A") and without modified
	      files.

	      If you trust your crew, have them notify you by Email.  Have
	      them send you the output from "cvs update" in their working
	      directory.  You might have to poll some people until you are
	      certain they have finished, or have given up.  (This is not
	      an invention.  I've heard a false, "Yeah, sure.  I finished
	      yesterday," more times that you'd believe.)

	      When all reports are in, go on to the Source Verification
	      stage.

	   B. Source Verification -- CVS and other Tools.

	      If you didn't dictate which ones to use, find all working
	      directories and run "cvs -n update" in all of them.  The
	      history command and the "commitinfo" log you set up might
	      help to find checked out working directories.

	      Sticky conflict flags will help, but they can't recover from
	      sloppiness or incompetence.  You might want to check
	      everything out into a tree and grep for the parts of the
	      merge conflict markers CVS doesn't look for.  CVS looks for
	      the string '^>>>>>>> '.  The merge operation also puts
	      '^<<<<<<< ' and '^======= ' markers in the file that
	      careless developers might leave there.

	      If you find problems simply by looking at the source files
	      and working directories, start the flogging now.	Resolving
	      the textual conflicts is the easy part.  Weed the turkeys
	      out before reaching the next part of the cleanup -- the
	      resolution of logical conflicts.

	      Then apply a set of post-commit tags.

	   C. Logical Verification -- Diff and powerful eyeballs.

	      No source control system can solve the problem of resolving
	      distributed conflicts in program logic.  If you change the
	      argument template for function A (defined in file A.c) and
	      add new calls to function A from within function B (defined
	      in file B.c) using the old argument format, you are outside
	      the realm of CVS's competence.

	      Assign someone to understand what the Vendor changed by
	      running "cvs diff -c -r <PreviousReleaseTag> <ReleaseTag>",
	      where the tags were those handed to the last two invocations
	      of "import".

	      Then have the same person compare that output (logically or
	      you can actually diff the diffs) to the output of the
	      similar "cvs diff -c -r <pre-import-tag> <post-commit-tag>".
	      The two sets of differences should be almost identical.
	      They should both show only the work *you* have performed.

	   D. Product Verification -- Build and Test.

	      Don't let your help off the hook until you verify that the
	      merge actually produced something that can compile and pass
	      tests.  Compiling should really be part of the logical
	      verification phase, but you should test the output of the
	      build system before declaring victory and releasing the
	      troops.


	9. After it is all built, apply another set of tags to mark the
	   end of the "import process".	  You can delete the intermediate
	   tags you added during source and logic testing, but keep the
	   "pre-import" and "post-import" tags forever.


	Of course, experience can tell you when to skip a step.	 But I'd
	start out by considering each one as necessary unless you can
	prove otherwise.



 3H.14	Explain: ERROR: cannot create link to <file>: Permission denied

	This error appears when you try to execute a second (or later)
	"import" into the same module from a directory to which you don't
	have write access.

	The "link error" is caused by a feature purposely added to
	speed up the import.

	Though the error message is somewhat strange, it indicates that
	"import" is supposed to be executed only in writable directories.


 3H.15	Where does the -m <message> go when the file doesn't change?

	The <message> handed to import is used as an RCS log message, but
	only if the imported file changed since the last version on the
	Vendor branch.	If the imported file hasn't changed, then no new
	revision is created.  The <ReleaseTag> is still applied, but to
	the previous revision.	So the Tags are still correct, but the
	message is lost.

	Maybe it should be appended to the previous log message.  But
	currently it isn't.


 3H.16	How do I "import" just the files ignored by a previous "import"?

	A real answer follows, but first, an editorial:

	    I am now convinced that you should always use the "-I !"
	    option.  Removing a few extraneous files from the Repository
	    is a lot easier than the recovery step described below.


	Let's assume your original import procedure was:
	(We assume there is enough disk space in /tmp.)

	    cd <head-of-vendor-tree>
	    cvs import -m 'xyz 1.3' gnu/xyz GNU GNUXYZ_1_3 | tee /tmp/IMP

	To import just the files ignored by "import", I would do this:

	1. Create a list of the ignored files to import:

	   cd <head-of-vendor-tree>
	   awk '/^I / {print $2}' /tmp/IMP | sed 's|^gnu/xyz/||' > /tmp/IG
	   [Edit the IG file to contain just the files you want.]

	2. Then create a sparse directory by handing your list to the GNU
	   version of "tar", installed in many places as "gtar":

	   mkdir /tmp/FIXUP
	   gtar -T /tmp/IG -c -f - . | (cd /tmp/FIXUP; gtar xvBf -)

	3. Then rerun the import.  Use the exact same command, but execute
	   it in the sparse directory tree you just created.  And this
	   time, tell it not to ignore anything.

	   cd /tmp/FIXUP
	   cvs import -I ! -m 'xyz 1.3' gnu/xyz GNU GNUXYZ_1_3


 3H.17	Why did "import" ignore all the symlinks?

	This is another design choice.

	Like the Unix "tar" command, "import" could sprout an option to
	follow symbolic links, but I don't think CVS will ever follow
	symbolic links by default.

	Two possible future enhancements have been seriously discussed:

	1. Treat symbolic links as data in its parent directory (the way
	   ClearCase does) in some sort of per-directory control file.

	2. Treat symbolic links as version-controlled elements themselves,
	   whose data is the value of readlink(2).

	For now, they are simply ignored.

	If you want to save and reconstruct symlinks, you might want to
	define a "checkout" or "update" program in the modules file which
	could consult a file kept under CVS in your working directory and
	make sure the specified links are in place.



----------------
-- Section 3I --	"log", "lo", "rlog"
----------------

 **** Questions:

 3I.1	What is "log" for?
 3I.2	How do I extract the log entries between two revisions?
 3I.3	How do I extract the log entries on a whole branch?
 3I.4	How do I generate ChangeLogs from RCS logs?
 3I.5	Why does "log" tell me a file was committed exactly 5 hours later
	than I know it was?


 **** Answers:

 3I.1	What is "log" for?

	To provide an interface to the RCS "rlog" command, which displays
	information about the underlying RCS files, including the revision
	history and Tag (RCS calls it a "symbol") list.


 3I.2	How do I extract the log entries between two revisions?

	If both <rev1> and <rev2> are on the same branch, you can get
	what you are looking for with:	(If they aren't on the same branch
	you'll either get an error or a display of the whole change log.)

		cvs log -r<rev1>:<rev2> <file>

	If you want all the revisions on the branch from <rev1> to the end
	of the branch <rev1> is on, you can use:

		cvs log -r<rev1>: <file>

	(If <rev1> is a numeric RCS symbol attached to a branch revision
	with an even number of '.'s in it, you get the whole branch.)

	If you want all the revisions on the branch from the beginning of
	the branch <rev2> is on up to revision <rev2>, you can use:

		cvs log -r:<rev2> <file>


	Note:	Depending on whether <rev1> and <rev2> are:

			- numeric or symbolic
			- in the file or not
			- on the same branch or not

		the RCS "rlog" (and therefore the "cvs log") command will
		display some combination of:

			- error messages
			- (intuitively correct) partial log listings
			- a display of the entire change log.


 3I.3	How do I extract the log entries on a whole branch?

		cvs log -r<rev> <file>

	where <rev> must be a branch revision (one with an even number
	of dots) or a *non-branch* tag on a branch revision.  Non-branch
	tags on a branch revision are not normally attached by CVS, to add
	one you will have to explicitly tag a physical branch number
	within each file.  Since these branch numbers are almost never the
	same in different files, this command is not all that useful.

	The intuitive command (at least from the CVS perspective):

		cvs log -r<branch_tag> <file>

	does not work.


 3I.4	How do I generate ChangeLogs from RCS logs?

	A program called rcs2log is distributed as part of GNU Emacs 19.
	A (possibly older) version of this program appears in the contrib
	directory of the cvs source tree.


 3I.5	Why does "log" tell me a file was committed exactly 5 hours later
	than I know it was?

	I can tell by this question that you were working in a time zone
	that is 5 hours behind GMT (e.g. the U.S. East Coast in winter).

	RCS file dates are stored in GMT to allow users in different time
	zones to agree on the meaning of a timestamp.  At first glance
	this doesn't seem necessary, but many companies use distributed
	file systems, such as NFS or AFS, across multiple timezones.

	Some standard form must be used.  GMT, as the "grid origin", is an
	obvious candidate.  The only other reasonable choice is to put the
	timezone information in all the time stamps, but that changes the
	RCS file format incompatibly, a step which has been avoided in the
	last few RCS releases.


----------------
-- Section 3J --	"patch", "pa", "rdiff"
----------------

 **** Questions:

 3J.1	What is "patch" for?
 3J.2	Why does "patch" include files from the Attic when I use '-D'?
 3J.3	How do I make "patch" produce a patch for one or two files?
	It seems to work only with modules.


 **** Answers:

 3J.1	What is "patch" for?

	To produce a "diff" between tagged releases to be handed to the
	"patch" command at other sites.	 This is the standard way that
	source patches are distributed on the network.


 3J.2	Why does "patch" include files from the Attic when I use '-D'?

	See the explanation of the same problem with "update -D"
	contained in section 5B.


 3J.3	How do I make "patch" produce a patch for one or two files?
	It seems to work only with modules.

	Patch is intended for producing patches of whole modules between
	releases to be distributed to remote sites.  Instead of "patch",
	you can use the "diff" command with the '-c' context option:

	     cvs diff -c -r <rev/tag> -r <rev/tag> <file1> . . .

	The patch command will be able to merge such a "diff" into the
	remote source files.

	If you configured CVS to use a version of "diff" that supports the
	'-u' option, you can produce a more compact "patch" in "unidiff"
	format.	 The latest revisions of the patch command can parse and
	apply patches in "unidiff" format.



----------------
-- Section 3K --	"release", "re", "rel"
----------------


 **** Questions:

 3K.1	What is "release" for?
 3K.2	Why can't I reverse a "cvs checkout path/name/subdir" with a
	"cvs release path/name/subdir" without an "unknown module name"?
 3K.3	Why can't I "release" portions of a checked out directory?  I
	should be able to "release" any file or sub-directory within
	my working directory.
 3K.4	I removed the tree that I was about to start working on.  How do I
	tell cvs that I want to release it if I don't have it anymore?
 3K.5	Why doesn't "release -d module" reverse a "checkout module"?
 3K.6	Why can't I release a module renamed with "cvs checkout -d"?


 **** Answers:

 3K.1	What is "release" for?

	To register that a module is no longer in use.	It is intended
	to reverse the effects of a "checkout" by adding a record to
	the history file to balance the checkout record and by
	optionally allowing you to delete the checked-out directory
	associated with the module name.


 3K.2	Why can't I reverse a "cvs checkout path/name/subdir" with a
	"cvs release path/name/subdir" without an "unknown module name"?

	A simplistic implementation.  (I can say this -- I wrote it.)

	The "release" function was written for CVS 1.2 under the
	assumption that the "module name" is a first class, unavoidable
	interface to the Repository, allowing no way to retrieve anything
	other than by module name.  Though it is easier to program that
	way, many users of CVS believe the modules support to be too
	primitive to allow such a limitation.

	Since "release" was written, other parts of CVS broke that
	assumption.  It needs to be revised.


 3K.3	Why can't I "release" portions of a checked out directory?  I
	should be able to "release" any file or sub-directory within
	my working directory.

	This isn't really a limitation in "release", per se.  CVS doesn't
	try to keep track of which files in which directories are "checked
	out" and which are just lying there.  You can delete directories
	and "update" will not bring them back unless you add a special
	"-d" option.

	In other words, CVS doesn't keep track of how you adjust the
	partition between files you consider part of your working set and
	files that were checked out because they are part of the same
	module or directory.  And neither does "release".

	In future CVS releases, "release" might become sophisticated
	enough to handle both the reversal of a "checkout" and the
	deletion of random portions of the working directory, but it isn't
	that way now.


 3K.4	I removed the tree that I was about to start working on.  How do I
	tell cvs that I want to release it if I don't have it anymore?

	See 3G.4.


 3K.5	Why doesn't "release -d module" reverse a "checkout module"?

	It does, if you are using "module" in a way that "release"
	expects: a non-alias string in the left column of the "modules"
	database.

	If "module" is really an alias, or if you are using a relative
	path in the place of "module", or if you renamed the directory
	with the -d option in the modules file or on the "checkout"
	command line, then the current version of "release" won't work.

	Future versions of "release" will probably fix most of these.


 3K.6	Why can't I release a module renamed with "cvs checkout -d"?

	The current version of "release" doesn't know how to track the
	renaming option ('-d') of the "checkout" command.  It will
	probably be fixed in the future.



----------------
-- Section 3L --	"remove", "rm", "delete"
----------------

 **** Questions:

 3L.1	What is "remove" for?
 3L.2	Why doesn't "remove" work on directories when it appears to try?
 3L.3	I don't like removing files.  Is there another way to ignore them?
 3L.4	I just removed a file.	How do I resurrect it?
 3L.5	Why doesn't "remove" delete the file?  Instead, it prints an
	error message and tells me to remove the file by hand.


 **** Answers:

 3L.1	What is "remove" for?

	To remove a file from the working branch.  It removes a file from
	the main branch by placing it in an "Attic" directory.


 3L.2	Why doesn't "remove" work on directories when it appears to try?

	Oversight.  It should be able to delete an empty directory, but
	you still don't have a way to remember when it was there and when
	it disappeared to allow the "-D <date>" option to work.

	You'll have to remove the working directory and the matching
	directory in the Repository.


 3L.3	I don't like removing files.  Is there another way to ignore them?

	There's no reason to be hasty in using the "remove" command.

	If there is a way to ignore files in your build procedures, I'd
	just do that.  Later, when you decide that the files are really
	ancient, you can execute a "remove" command to clean up.

	The CVS "ignore" concept can't ignore files already in CVS.


 3L.4	I just removed a file.	How do I resurrect it?

	If you executed "remove", but haven't typed "commit" (you can
	tell this by the 'R' notation that "update" prints next to the
	file), you can execute "add" to reverse the "remove".

	If you followed the "remove" with a "commit", you'll have
	to move it back out of the Attic by hand:

	I use something like this: (csh-like syntax)

		set repos = `cat ./CVS/Repository`
		mv $repos/Attic/filename,v $repos/filename,v

	(If you use relative paths in your Repository files, that first
	line becomes: set repos = $CVSROOT/`cat ./CVS/Repository`)

	While a file is in the Attic, you can't "add" another file by
	the same name.	To add such a file you either have to move it by
	hand as in the above, or delete it from the Attic.

	The main reason for the Attic is to retain files with tags in
	them.  If you execute: "update -r <oldtag>", files with <oldtag>
	attached to some revision will be taken from the normal Repository
	area and from the Attic.  That's why you can't "add" a file with
	the same name.	"remove" only moves a file off the main branch, it
	doesn't obliterate it.


 3L.5	Why doesn't "remove" delete the file?  Instead, it prints an
	error message and tells me to remove the file by hand.

	Design choice.	Unix software written within last decade, usually
	requires an extra verification step, such as answering a question
	or adding a flag on the command line.  CVS currently requires that
	you delete the file first unless you specify the '-f' (force)
	option, which deletes the file before performing "cvs remove".



----------------
-- Section 3M --	"rtag", "rt", "rfreeze"
----------------

(See the "tag" section below for the general questions about Tagging, which
 "tag" and "rtag" share in common.)


 **** Questions:

 3M.1	What is "rtag" for?
 3M.2	Why use "rtag"?	 It assumes no one is changing the Repository.
 3M.3	What revision does "rtag -r <tag1> <tag2>" actually put the tag on?
 3M.4	What happens if the tags are the same in "rtag -r <tag> <tag>"?
 3M.5	Why doesn't "rtag -b -r <branch_tag1> <branch_tag2>" rename or
	duplicate a magic branch tag?


 **** Answers:

 3M.1	What is "rtag" for?

	To add a symbolic label (a "tag") to the last committed revisions
	of a module directly in the Repository.


 3M.2	Why use "rtag"?	 It assumes no one is changing the Repository.

	Though the "tag" command is more useful in marking the
	revisions you have in a particular working directory, "rtag" is
	much handier for whole-Repository actions, which occur at major
	release boundaries.


 3M.3	What revision does "rtag -r <tag1> <tag2>" actually put the tag on?

	In short, the '-r' option is another way to select the revision to
	tag.  The revision is selected the same way for all commands that
	accept a "-r <tag/rev>" option.

	Depending on whether <tag1> is a <branch_tag>, or a non-branch
	<tag> and on whether you use the '-b' option to "rtag", you get
	four different results:

	1. rtag -r <tag1> <tag2>

	   Adds the non-branch tag <tag2> to the same revision that the
	   non-branch tag <tag1> is attached to.

	   Example:
		<tag1>		--> TT1
		<tag2>		--> TT2
		<file>		--> Symbols: TT1:1.4
		After		--> Symbols: TT1:1.4,TT2:1.4


	2. rtag -r <branch_tag1> <tag2>

	   Adds the non-branch tag <tag2> to the HEAD of (the highest
	   revision number on) the branch labelled with tag <branch_tag1>.

	   Example:
		<branch_tag1>	--> BR1
		<tag2>		--> TT2
		<file>		--> Symbols: BR1:1.2.0.2 (1.2.2.5 is HEAD)
		After		--> Symbols: BR1:1.2.0.2,TT2:1.2.2.5

	   If the branch tagged by <branch_tag1> has not been created,
	   then the tag shows up on the branch point revision:

	   Example:
		<branch_tag1>	--> BR1
		<tag2>		--> TT2
		<file>		--> Symbols: BR1:1.2.0.2 (No 1.2.X exists.)
		After		--> Symbols: BR1:1.2.0.2,TT2:1.2


	3. rtag -b -r <tag1> <branch_tag2>

	   Adds the magic branch tag <branch_tag2> to the revision that
	   the non-branch tag <tag1> is attached to, preparing it to be a
	   branch point.

	   Example:
		<tag1>		--> TT1
		<branch_tag2>	--> BR2
		<file>		--> Symbol: TT1:1.4
		After		--> Symbol: TT1:1.4, BR2:1.4.0.2


	4. rtag -b -r <branch_tag1> <branch_tag2>

	   Adds the magic branch tag <branch_tag2> to the revision at the
	   HEAD of (the highest revision number on) the branch labelled
	   with <branch_tag1>, preparing it to be a branch point.

	   Example:
		<branch_tag1>	--> BR1
		<branch_tag2>	--> BR2
		<file>		--> Symbol: BR1:1.2.0.2 (1.2.2.5 is HEAD)
		After		--> Symbol: BR1:1.2.0.2,BR2:1.2.2.5.0.2

	   If the branch tagged by <branch_tag1> has not been created,
	   then the tag shows up as a second branch off the same
	   branch point revision:

	   Example:
		<branch_tag1>	--> BR1
		<tag2>		--> TT2
		<file>		--> Symbols: BR1:1.2.0.2 (No 1.2.X exists.)
		After		--> Symbols: BR1:1.2.0.2,TT2:1.2.0.4



	In all four cases above, if <tag2> already exists on the file, you
	get an error unless you specify the '-F' option.

	In all four cases, if <tag1> does not exist on the file, <tag2> is
	not added unless you specify the '-f' option.


 3M.4	What happens if the tags are the same in "rtag -r <tag> <tag>"?

	Again, there are four cases depending on whether <tag> is a
	branch tag, or a non-branch tag and on whether you use the
	'-b' option to "rtag":

	1. rtag -r <tag> <tag>

	   Is a no-op.	It does nothing even with '-F' specified.

	   If you add the '-f' option ("rtag -f -r <tag> <tag>"), then
	   <tag> is attached to the latest revision on the Main Branch if
	   the file does *not* already have <tag> on some revision.

	   If the <tag> is already on the file, using "rtag -f" is still
	   a no-op.


	2. rtag -r <branch_tag> <branch_tag>

	   Produces an error, since the <branch_tag> is already on some
	   revision of the file.

	   But, "rtag -F -r <branch_tag> <branch_tag>" turns the magic
	   branch tag into a non-branch tag.

		Symbols: BR1:1.4.0.2
	   becomes
		Symbols: BR1:1.4


	3. rtag -b -r <tag> <tag>

	   Produces an error, since the <tag> is already on the file.

	   But, "rtag -F -b -r <tag> <tag>" turns the non-branch
	   tag into a magic branch tag.

		Symbols: BR1:1.4
	   becomes
		Symbols: BR1:1.4.0.2


	4. rtag -b -r <branch_tag> <branch_tag>

	   Produces an error, since the <branch_tag> is already on the
	   file.

	   But, "rtag -F -b -r <branch_tag> <branch_tag>" increments the
	   branch number.  It essentially removes the branch and creates a
	   new one by the same name.

		Symbols: BR1:1.2.0.4
	   becomes
		Symbols: BR1:1.2.0.6



 3M.5	Why doesn't "rtag -b -r <branch_tag1> <branch_tag2>" rename or
	duplicate a magic branch tag?

	None of the "tag" or "rtag" options rename anything.  They only
	apply (or, with the '-F' option, move) tags to specific revisions
	in the file.

	See 3M.[3-4] above for details of how it works.

	To rename a non-branch tag, see 3O.9.
	To rename a magic branch tag, see 4D.5



----------------
-- Section 3N --	"status", "st", "stat"
----------------

 **** Questions:

 3N.1	What is "status" for?
 3N.2	Why does "status" limit the File: at the top to 17 characters?
 3N.3	Why does it print "Sticky" lines when the values are "(none)"?
 3N.4	Shouldn't the status "Needs Checkout" be "Needs Update"?


 **** Answers:

 3N.1	What is "status" for?

	To display the status of files, including the revision and branch
	you are working on and the existence of "sticky" information.


 3N.2	Why does "status" limit the File: at the top to 17 characters?

	Designed that way to line up with other data.  You can find the
	whole filename in the line beginning with "RCS version:", which is
	not limited in length.


 3N.3	Why does it print "Sticky" lines when the values are "(none)"?

	Oversight.  It should probably elide lines without information.


 3N.4	Shouldn't the status "Needs Checkout" be "Needs Update"?

	Probably.

	[[Did this show up in CVS 1.4?]]



----------------
-- Section 3O --	"tag", "ta", "freeze"
----------------

 **** Questions:

 3O.1	What is "tag" for?
 3O.2	What is the difference between "tag" and "rtag"?
 3O.3	Why does "tag -b" not put a tag on the Branch Point revision?
	How do I refer to the Branch Point?
 3O.4	So "{r}tag" labels a bunch of files.  What do you use a Tag for?
 3O.5	How do I get "tag" and "rtag" to send mail the way "commit" does?
 3O.6	Why can't "tag" handle the '-r' option that "rtag" takes?
 3O.7	After a "tag <tag>" in my working directory, why doesn't "checkout
	-r <tag>" somewhere else produce copies of my current files?
 3O.8	Why doesn't "tag" write a history record the way "rtag" does?
 3O.9	How do I rename a <tag>?


 **** Answers:

 3O.1	What is "tag" for?

	To add a symbolic label (a "tag") to the RCS files last checked
	out, updated or committed in a working directory.


 3O.2	What is the difference between "tag" and "rtag"?

	The end result of both commands is that a <tag>, or symbolic name,
	is attached to a single revision in each of a collection of files.

	The differences lie in:

	1. The collection of files they work on.

	    "rtag" works on the collection of files referred to by a
	    "module" name as defined in the "modules" file, or a relative
	    path within the Repository.

	    "tag" works on files and directories specified on the command
	    line within the user's working directory.  (Default is '.')

	    Both commands recursively follow directory hierarchies within
	    the named files and directories.

	2. The revisions they choose to tag.

	    "rtag" places a tag on the latest committed revision of
	    each file on the branch specified by the '-r' option.  By
	    default it tags the Main Branch.

	    "tag" places a tag on the BASE (i.e. last checked out, updated
	    or committed) revision of each file found in the working
	    directory.	(The BASE revision of a file is the one stored in
	    the ./CVS/Entries file.)

	3. A different set of command line options.

	   For example, "rtag" takes a "-r <oldtag>" option to retag an
	   existing tag.  The "tag" command does not.

	4. How it is logged.

	   Currently "rtag" records the <tag> and the module in the
	   "history" file, while "tag" does not.


 3O.3	Why does "tag -b" not put a tag on the Branch Point revision?
	How do I refer to the Branch Point?

	This is probably an oversight, or a disbelief in the need for it.
	If everything works perfectly, the "update -j" command will do the
	merge you need and you don't need to check up on it by playing
	with the branch point revision.

	The '-b' option attaches a magic branch tag to allow CVS later to
	figure out the branch point.  The actual revision that <tag> is
	attached to does not exist.  References to the branch tag are
	equivalent to references to the latest revision on the branch.

	There is no way to refer to the branch point without adding a
	non-branch tag.	 You might want to add non-branch tags as a
	habit and add branch tags later, possibly immediate after adding
	the non-branch tag.  See 4C.3 on Creating a Branch.


 3O.4	So "{r}tag" labels a bunch of files.  What do you use a Tag for?

	You use it to "checkout" the labeled collection of files as a
	single object, referring to it by name.

	Anywhere a revision number can be used a Tag can be used.  In fact
	tags are more useful because they draw a line through a collection
	of files, marking a development milestone.

	The way to think about a Tag is as a curve drawn through a matrix
	of filename vs. revision number.  Consider this:

	Say we have 5 files (in some arbitrary modules, some may be in 2
	or more modules by name, some may be in 2 or more modules because
	of the Repository tree structure) with the following revisions:

		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

	At some time in the past, the '*' versions were tagged.	 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 draw a
	straight line through the set of revisions you care about and
	shuffle the other revisions accordingly.  Like this:

		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

	I find that using these visual aids, it is much easier to
	understand what a <tag> is and what it is useful for.


 3O.5	How do I get "tag" and "rtag" to send mail the way "commit" does?

	The "commit" command is supported by two files ("commitinfo"
	and "loginfo") not used by other commands.  To do logging the
	same way for "tag" and "rtag" would require another file like
	loginfo, which currently doesn't exist.

	The "rtag" command requires a "module" entry, which can specify a
	"tag" program using the "-t programname" option on the module
	line.

	There is no equivalent support for "tag".


 3O.6	Why can't "tag" handle the '-r' option that "rtag" takes?

	Oversight.  The answer is probably "Fixed in a Future Release."


 3O.7	After a "tag <tag>" in my working directory, why doesn't "checkout
	-r <tag>" somewhere else produce copies of my current files?

	The only reason this would fail, other than misspelling the <tag>
	string, is that you didn't "commit" your work before "tagging" it.
	Only committed revisions may be tagged.	 Modified files are not
	marked for later tagging.


 3O.8	Why doesn't "tag" write a history record the way "rtag" does?

	The "rtag" command was originally intended to place major
	"release" tags onto modules.  The "tag" functionality was
	developed to *move* the more significant tag when slight changes
	to individual files sneaked in after the release tag was stamped
	onto the Repository.

	The significant event was the "rtag", which was recorded in the
	"history" file for the "history -T" option to work.

	It turns out that "tag" is generally more useful than "rtag", so
	the model has changed.	Future revisions of CVS will probably
	store both kinds of tags in the history file.


 3O.9	How do I rename a <tag>?

	For a procedure to rename a branch tag, See section 4D.5
	The following covers only non-branch tags.

	First, pick a <newtag> that is not in use.  You could reuse
	(i.e. move) an existing tag to the new revisions using the '-F'
	option, but that will confuse matters when both tags are not
	already on a file.  (It will probably confuse "rtag -f" too.)

	Use "rtag" to place <newtag> only on revisions attached to
	<oldtag> in the whole Repository, then delete the old one.

		cvs rtag -r <oldtag> <newtag> world
		cvs rtag -d <oldtag> world.


	You can also checkout or update your working directory to the
	<oldtag> and "tag" rather than "rtag" the result.  But that
	will take longer and it has the chance of producing conflicts.

		cvs update -r <oldtag>
		cvs tag <newtag>
		cvs tag -d <oldtag>
		cvs update -A  (or cvs update -r <previous_tag>)


----------------
-- Section 3P --	"update", "up", "upd"
----------------

 **** Questions:

 3P.1	What is "update" for?
 3P.2	What do 'U', 'M' and 'C' mean when I type "update"?  Are they
	different for "cvs -n update"?
 3P.3	What's the difference between "update" and "checkout"?
 3P.4	Why don't I get new files when I execute "update"?
 3P.5	Why does "update" say 'M' both for plain modified files and for
	successful (i.e. conflict-free) merges?	 Aren't they different?
 3P.6	What's a "sticky conflict"?  How does it know a conflict occurred?
 3P.7	Is there a feature to tell me what I have changed, added and
	removed without changing anything?
 3P.8	Why were all my files deleted when I executed "update"?


 **** Answers:

 3P.1	What is "update" for?

	The "update" command is by far the most important command and is
	probably also the most used command.

	It has five purposes:  (And many options.)

	1. To display the status of your working files.

	   Though a plain "update" also displays the status, it does so
	   after possibly altering your working directory.  To see the
	   status of your working files without changing anything, type:

		cvs -n update {optional list of files}


	2. To merge changes made by others to the branch you are working
	   on into your working files.

	   Each working directory is attached to a branch, usually the
	   Main branch.	 To merge changes made on your working branch
	   since your last checkout,  update or commit, type:

		cvs update {optional list of files}


	3. To merge changes made on another branch into the branch you are
	   working on (your "working branch").

	   If you want to grab a whole branch, from the branch point,
	   which is assumed to be on the Main Branch, to the end of the
	   branch, you type:

		cvs update -j <branch_tag> {optional files}

	   If you want to grab the changes made between two tags or
	   revisions, you type:

		cvs update -j <tag1> -j <tag2> {optional files}

	   (If you are working with a single file, the Tags could also be
	    revisions numbers.	Unless you take great care to match
	    revision numbers across different files (a waste of time given
	    the way Tags work), using revision numbers in place of the
	    Tags for multiple files would be meaningless.)


	4. To move your working directory to another branch.

	   A working directory is presumed to be attached to (or working
	   on) a particular branch, usually the Main branch.  To alter
	   what CVS believes to be your working branch, you "move" to that
	   branch.

	   To move to a tagged branch, type:

		cvs update -r <branch_tag> {optional files}

	   To move to the Main Branch, type:

		cvs update -A {optional files}

	   If you have modified files in your working directory, this is
	   not a clean move.  CVS will attempt to merge the changes
	   necessary to make it look like you made the same changes to the
	   new branch as you made in the old one.  But if you do this
	   twice without resolving the merge conflicts each time, you can
	   lose work.


	5. To retrieve old revisions of files.

	   This option is similar to 4 above but you are not restricted to
	   using a <branch_tag>.  You may specify any revision or <tag>
	   with '-r' and get the specified revision or the tagged
	   revision:

		cvs update -r <tag/rev> {optional files}

	   Or you may specify any date with '-D':

		cvs update -D <date> {optional files}

	   The '-p' option sends the revisions to standard output
	   (normally your terminal) rather than setting the "sticky" tag
	   and changing the files.


 3P.2	What do 'U', 'M' and 'C' mean when I type "update"?  Are they
	different for "cvs -n update"?

	"cvs update" merges changes made to the Repository, since your
	last "checkout", "update" or "commit", into your working files.
	You can think of it as changing your BASE revision.

	"cvs update" prints lines beginning with:

	'U'	after replacing your unmodified file with a different
		revision from the Repository.

	'M'	for two different reasons:

		1. for files you have modified that have not changed in
		   the Repository.

		2. after a merge, if it detected no conflicts.

	'C'	after a merge, if it detected conflicts.  See 2D.7 and
		3P.6 for more info on conflict resolution and "sticky
		conflicts."

	"cvs -n update" shows what it *would* do, rather than doing it.
	Or, another way of looking at it, "cvs -n update" displays the
	relationship between your current BASE revisions (identified in
	your ./CVS/Entries file) and the HEAD revisions (the latest
	revisions in the Repository).

	"cvs -n update" prints lines beginning with:

	'U'	for files you have not modified that have changed in the
		Repository.

	'M'	for files you have modified that have not changed in the
		Repository.

	'C'	for files you have modified that have also been changed in
		the Repository.


	See 4C.6 for what the letters mean when merging in from another
	branch.	 The output is almost the same for a normal update if you
	consider the Repository as the branch and your working directory
	as the "trunk".


 3P.3	What's the difference between "update" and "checkout"?

	See 3C.4 above.


 3P.4	Why don't I get new files when I execute "update"?

	There are six reasons for nothing to happen during an "update":

	1. Nothing on your branch changed in the Repository.

	   If no one has committed anything to the branch you are working
	   on (normally the Main branch) since the last time you executed
	   "checkout", "update" or "commit", nothing will happen.

	   It's like shouting "xyzzy" or "plugh" in the wrong room.

	2. You have a "sticky" non-branch <tag> or <date> attached to the
	   working files you are trying to "update".

	   At some time in the past you checked out or updated your
	   directory with the "-r <tag>" or "-D <date>" option.	 Until you
	   do it again with a different tag or date, or go back to the
	   Main Branch with "update -A", you will never again see any
	   updates.

	3. The ./CVS/Entries.Static file exists and you are expecting a
	   new file.

	   If your ./CVS administrative directory contains a file named
	   Entries.Static, no files will be checked out that aren't
	   already in the Entries or Entries.Static file.

	4. You forgot to use the '-d' option and are looking for new
	   directories.

	   If you execute "update" without the '-d' option, it will not
	   create new directories that have been added to the Repository.

	5. You typed "update" instead of "cvs update".

	   On most Unix systems, your disk caches are now furiously being
	   flushed by multiple update daemons, destroying performance and
	   proving to management that you need more CPU power.	:-)

	   On HP systems you might be asked what package you want to
	   install from the "update server".

	6. Someone removed (using "admin -o") your BASE revision (the
	   revision CVS thought you had in your working directory), then
	   committed a "replacement".  CVS is now confused because the
	   revision in the Repository matches your BASE revision when the
	   files themselves don't match.  See 3B.6.


 3P.5	Why does "update" say 'M' both for plain modified files and for
	successful (i.e. conflict-free) merges?	 Aren't they different?

	A design choice.  Yes, they are different internally, but that
	shouldn't matter.  Your files are in the same condition after the
	"update" as they were before -- a "diff" will display only your
	modifications.	And you are expected to continue onward with parts
	two and three of the normal development cycle: "emacs" (a synonym
	for "edit" in most of the civilized world) and "commit".


 3P.6	What's a "sticky conflict"?  How does it know a conflict occurred?

	When a "cvs update" (or an "update -j") creates a conflict, it
	prints a 'C' and stores the timestamp of the file after the merge
	in a special field in the ./CVS/Entries file.

	This conflict indication implies that the merge command altered
	your working file to contain conflict markers surrounding the
	overlapping code segments.  For example, say that

	- Two developers acquire revision 1.2 of <file> via "checkout" or
	  "update".

	- Developer A changes line 1 from "9999" to "5555", then commits
	  the file, creating revision 1.3.

	- Developer B changes line 1 from "9999" to "7777", then tries to
	  commit the file, but is blocked because the file is not up to
	  date.	 Developer B then runs "update" and sees the conflict
	  marker 'C'.  The beginning of the file would look like this:

	    <<<<<<< <file>	The working <file> in question.
	    7777		Change made to the working <file>.
	    =======
	    5555		Change made in the first commit (1.3)
	    >>>>>>> 1.3		The revision created by the first commit.

	The conflict is "sticky", which means that until the conflict is
	cleared, the "update" command will continue to display the file's
	status as 'C' and the "status" command will show the file's status
	as "Unresolved Conflict".

	Until the conflict is cleared, "commit" is blocked for this file.

	The sticky conflict indicator can be cleared by:

	1. Resolving the conflict by editing the file.	Two things must
	   happen before the conflict is considered resolved:

		The timestamp of the file must change.
	   *and*
		The file must contain no conflict markers.  (The string
		searched for in the file is the regexp: "^>>>>>>> ".)

	   After clearing the sticky conflict indicator, you may then
	   commit the file normally.

	2. Removing the file and running "update".  This throws away the
	   local changes and accepts the latest committed file on this
	   branch.   No commit is needed.

	3. Forcing the commit to happen by using "commit -f".  This is
	   probably a mistake since there are few lines of real
	   text that begin with ">>>>>>> ".


 3P.7	Is there a feature to tell me what I have changed, added and
	removed without changing anything?

	The command "cvs -n update" will do exactly that.


 3P.8	Why were all my files deleted when I executed "update"?

	You probably executed "update -r <tag>" some time ago, then
	removed <tag> from the Repository files.  "update -r <tag>" will
	delete a file that doesn't contain <tag>.

	A way to fix this is to "cd" into your working directory and
	type:

		cvs update -A

	If you don't want the latest revisions on the Main (or Vendor)
	Branch, then decide what Tag (normal or branch) you want and type:

		cvs update -r <the_tag_you_want>

	Another way to make a file disappear is to execute "update -D
	<date>" where <date> is before the date stamped onto the first
	revision in the RCS file.



===============================================
==  Section 4	====	Advanced Topics	   ====
===============================================

----------------
-- Section 4A --	Installing CVS
----------------

 **** Questions:

 4A.1	What do I have to do before I install CVS?
 4A.2	How do I configure the CVS programs?
 4A.3	What do I have to install?
 4A.4	How do I work around the merge problems in GNU diff version 2.1
	or later?


 **** Answers:

 4A.1	What do I have to do before I install CVS?

	1. You must decide where to set up a Repository.

	   Though you can construct a Repository tree structure using
	   links and mount points, there must be a single copy of each
	   real file across your entire organization.  You may not "rdist"
	   files and expect to edit both copies.

	   CVS does not support a truly distributed Repository.	 You can
	   have multiple Repositories, but each one must be mounted (not
	   copied or "rdist"ed) from a single place onto all machines
	   where it will be used.

	   Initially, a Repository takes about same amount of disk space
	   as the sources you want to put into it, plus a bit of overhead
	   for the RCS files.

	   See Section 4B.  For multiple Repositories, see 4G.3

	2. You need a directory in everyone's $PATH variable where you can
	   install all the executables.	 /usr/local/bin is a common place.

	3. You need some helper tools besides CVS such as "RCS" and a
	   good set of "diff" and "diff3" programs.  See 1B.4 for
	   suggestions.

	4. Read the README, INSTALL and ChangeLog files to see what you
	   are getting into.

	5. Make sure you have versions of all the programs mentioned in
	   the "cvs/src/options.h" and "cvs/src/rcs.h" files.

	6. Though you can probably muddle along without it, you should
	   appoint one or more "Repository Administrators" who will be
	   responsible for maintaining the Repository structure,
	   administrative files and the "modules" interface.

	   Someone at your site should probably be on the info-cvs mailing
	   list.  See 1B.5.


 4A.2	How do I configure the CVS programs?

	1. You should certainly start by reading the README file, the
	   INSTALL files and possibly the ChangeLogs in each directory,
	   the Makefile.in files and the "cvsinit.sh" program.

	2. Edit the "options.h" file in the "src" directory.

	   You might need to specify a few site-specific pieces of
	   information including the names of a number of functions.

	   Hint1:  You probably want to set the DIFF macro to use your
		   version of the GNU diff program with the '-a' option.
		   Ours is set to "gdiff -a".

	   Hint2:  You want to use RCS 5.6.0.1 or greater and set the
		   "HAVE_RCS5" macro.

	3. Execute the ./configure command.

	4. Type "make".

	5. After running "make" you might try running the "sanity.sh"
	   script:
		./src/sanity.sh `pwd`/src/cvs

	   It writes into /tmp/cvs-sanity by default.

	6. Finish reading the INSTALL file and test out the system.


 4A.3	What do I have to install?

	1. Install the "cvs" executable and "mkmodules" from the CVS
	   sources.  The man page is useful too.  If you plan to report
	   bugs, you should also install "cvsbug".

	2. Make sure you have versions of all the programs mentioned in
	   the options.h file, most of which are included in a standard
	   Unix system.

	3. Unless you plan to reimplement RCS [:-)], you must install RCS.

	   It is a very good idea to examine the RCS installation
	   instructions and make sure you are using the GNU versions of
	   "diff" and "diff3" or merges (an important part of CVS) will
	   not work as well as you'd like.

	4. Set your $CVSROOT environment variable and create the
	   Repository (which you planned out in 4A.1) with the "cvsinit"
	   command at the top of the CVS sources.

	5. You'll need to edit the Repository control files created by
	   "cvsinit".

	6. Install any helper programs mentioned in the modules file.


 4A.4	How do I work around the merge problems in GNU diff version 2.1
	or later?

	See 1B.4  If you use recent versions of RCS and "diff", you won't
	run into the above.  If you do, see 5B.8


----------------
-- Section 4B --	Setting up and Managing the Repository
----------------

 **** Questions:

 4B.1	What do I do first?  How do I create a Repository?
 4B.2	What are those files in $CVSROOT/CVSROOT?
 4B.3	Is there any other state stored in the Repository besides in the
	$CVSROOT/CVSROOT directory?
 4B.4	How do I put sources into the Repository?
 4B.5	What file permissions should I use on (and in) the Repository?
 4B.6	How do I structure my Repository?
 4B.7	Why would anyone use "modules"?	 They are too restrictive.  I
	want to be able to select just the files I want to edit.
 4B.8	How do I rename a file or directory?  What are the consequences?
 4B.9	What are "Attic" directories?
 4B.10	Is it OK to remove anything from the Repository?
 4B.11	Can I convert to CVS from RCS without losing my revision history?
 4B.12	Can I move RCS files with branches in them into the Repository?
 4B.13	Can I use raw RCS commands on the Repository?
 4B.14	How do I convert from SCCS to RCS?
 4B.15	How do I limit access to the Repository?
 4B.16	What are the Repository Administrator's responsibilities?
 4B.17	How do I move the whole Repository?
 4B.18	How do I change permissions on a file in the Repository by using
	a CVS command?	(i.e. without using "chmod 777 $CVSROOT/dir/file")


 **** Answers:


 4B.1	What do I do first?  How do I create a Repository?

	First, install all the programs. (See Section 4A.)

	Then create a Repository by executing "cvsinit", which works only
	from within the head of the CVS source directory.  (It needs files
	from the distribution to work.)

	If you want a very primitive Repository and don't want to save a
	history log, refer to modules, or use any of the "info" files for
	logging, pre-commit checks, or editing templates, you can dispense
	with "cvsinit" entirely.  I would advise executing it.

	The cvsinit program will create a short modules file containing
	the module named "CVSROOT".  To to your work directory and type:

		cvs checkout CVSROOT

	Then read the files that are checked out.

	You will certainly want to add modules of your own.  Edit the
	"modules" file and add lines to describe the items you want to
	"checkout" by module name.  Here's a short list that could be
	used for storing a small number of GNU and PD sources:

		local	local

		gnu	local/gnu
		emacs	local/gnu/emacs
		cvs	local/gnu/cvs

		public	local/public
		pdprog1 local/public/pdprog1
		pdprog2 local/public/pdprog2

		test	test
		junk	test/junk


	When you are done editing, "commit" the modules file.  If you
	configured CVS to use "dbm", you might have to edit and commit the
	modules file twice to change the pathname of the mkmodules program
	in the modules file.

	Try using the "import" command to insert the "junk" module
	and play around until you are comfortable.



 4B.2	What are those files in $CVSROOT/CVSROOT?

	There are eight Repository control (or "database") files of
	interest in the CVSROOT directory:

	1. modules	contains the "modules" database.  See 1D.11, 2C.7,
			4B.6 and 4B.7 for more details.

	2. commitinfo	contains two columns: 1. a regular expression to
			match against pathnames within the Repository and
			2. a <command> to execute for matching pathnames.

			When you execute "commit", CVS passes the
			Repository pathname for each directory (and the
			files to commit within that directory) to
			<command>.  If <command> exits with a non-zero
			status, the commit is blocked.

			A <command> associated with a pathname of
			"DEFAULT" is executed if nothing else matches.
			Every <command> associated with a pathname of
			"ALL" is executed separately.

	3. rcsinfo	contains the same first column as commitinfo, but
			the second column is a template file for
			specifying the log entry you are required to enter
			for each commit.

			"DEFAULT" and "ALL" work the same as in the
			commitinfo file.

	4. editinfo	contains the same two columns as commitinfo, but
			the <command> in the second column is intended to
			do some consistency checking on the commit log.

			"DEFAULT" works as in commitinfo.

	5. loginfo	contains the same two columns as commitinfo, but
			the <command> is expected to read a log message
			from its standard input.  The <command> can do
			anything it wants with the log information, but
			normally it is appended to a log file or sent to
			mailing lists.

			"DEFAULT" & "ALL" work the same as in commitinfo.

	6. cvsignore	contains "ignore" patterns that are added to the
			built-in ignore list.  See 2D.10.

	7. checkoutlist contains a list of other files kept under RCS in
			$CVSROOT/CVSROOT that should be checked out by
			mkmodules to provide a readable copy.

	8. history	contains a stream of text records, one for each
			event that the "history" command is interested
			in.  Though the contents of the history file can
			be read, it is intended to be read and displayed
			by the "history" command.  This file is the only
			one in the above list that is not under RCS.


 4B.3	Is there any other state stored in the Repository besides in the
	$CVSROOT/CVSROOT directory?

	Only in the RCS files.	The Repository holds exactly two things:
	the tree of RCS files (each usually ending in ",v") and the
	CVSROOT directory described above.


 4B.4	How do I put sources into the Repository?

	There are three main ways to put files in the Repository:

	1. Use the "import" command described in Section 3H.

	   This method is the fastest way to put trees of new code into
	   the Repository and the *only* way to handle source releases
	   from a 3rd party software vendor.

	2. Use "add" followed by "commit".

	   This is how to add new files and directories to the Repository,
	   a few at a time.  Directories don't need to be committed.

	3. You can move RCS files directly into the Repository.

	   You should create a directory hierarchy to hold them, but you
	   can just move arbitrary ",v" files into the Repository.  The
	   only "state" in the Repository other than within ",v" files is
	   in the required CVSROOT directory at the top of the Repository.


 4B.5	What file permissions should I use on (and in) the Repository?

	If you run a completely open environment (which usually means that
	you don't have, or don't want to waste, the time to deal with it):

	   - Set all directory permissions to 777.

	   - Have everyone set their umasks to 0.

	   (BTW, I don't suggest this.	I am merely reporting it.)


	If you are a normal Unix shop and want to use groups effectively:

	   - Set all the directory permissions in the Repository to 775.

	     If you are using a system that handles both System V and BSD
	     filesystems, you might have to set the permissions to 2775.)

	     If you are using one of the many recent versions of Unix that
	     don't allow you to use the full octal mode, then you'll have
	     to type:  chmod u=rwx,g=rwx,o=rx,g+s <dir>

	   - Change all the groups on the directories to match the groups
	     you want to write to various directories.

	   - Make sure every user is in the appropriate groups.

	   - Have everyone set their umask to 002, including root.


	If you don't want non-group members to even read the files, do the
	above, but change:

	   - Repository directory permissions to 770. (or 2770)

	   - umasks to 007.


	If you work in an environment where people can't be trusted to
	set their "umask" to something reasonable, you might want to set
	the umask for them:

		mv /usr/local/bin/cvs /usr/local/bin/cvs.real
		cat > /usr/local/bin/cvs
		#!/bin/sh
		umask 2		# Or whatever your site standard is.
		exec /usr/local/bin/cvs.real ${1+"$@"}
		^D


 4B.6	How do I structure my Repository?

	The Repository holds your software.  It can be all interrelated
	or it can be a bunch of separately managed directories.

	How you break a whole system down into its component parts, while
	defining interfaces between them, is one aspect of "Software
	Engineering", a discipline that requires the study of dozens of
	strange and wonderful areas of the computer and management worlds.

	CVS provides a way to keep track of changes to individual files,
	a way to "tag" collections of files, and a way to "name"
	collections of files and directories.  That's all.  Everything
	else is in the way you apply it.

	In other words, you should structure your Repository to match your
	needs, usually tied in with the other tools you use to build,
	install and distribute your work.  Common needs include the
	ability to:

	  - mount (or automount) directories from many places in your
	    organization.
	  - check out just what you need and no more.
	  - check out multiple sections in a fixed relation to each other.
	  - check out large sections to match the assumptions built into
	    your build system. (Makefiles?)

	In my opinion, you should start small and keep everything in one
	tree, placing each major sub-system into a separate directory.
	Later, when you know what you are doing, you can make it more
	sophisticated.


 4B.7	Why would anyone use "modules"?	 They are too restrictive.  I
	want to be able to select just the files I want to edit.

	Any form of structure is restrictive.  If you believe that total
	chaos is a viable working paradigm, or if you believe you can keep
	track of the interrelations between all portions of your
	Repository in your head, then you can do what you please.

	If you believe that systems of files require management and
	structure, then the "modules" idea is very useful.  It is a way
	to impose a naming scheme on a tree of files, a naming scheme that
	can be simpler than a large list of relative pathnames.

	The "modules" file represents a published interface to the
	Repository set up by your Repository Administrator.  If s/he did a
	creditable job, the modules offered will be internally consistent
	and will smoothly interact with the rest of your environment.


 4B.8	How do I rename a file or directory?  What are the consequences?

	In CVS there is no single "rename" command.

	See 2C.4 for the suggested way to rename a file or directory.

	The rest of this section covers some of the consequences of
	renaming.

	A "renaming database" has been proposed that would keep track
	of name changes so that "update -r <tag>" would continue to
	work across the renaming.  But as it stands, you have to pick
	one of the following options:

	1. Use the technique described in 2C.4.	 (For each file, duplicate
	   the file in the Repository, "remove" the old version so it
	   winds up in the Attic and strip all Tags off the new version.)

	   - "update -r <tag>" produces the correct files.

	   - The duplicated revision history can be slightly misleading.

	   - A plain (i.e. without the "-r <tag>") "checkout" or "update
	     -d" will create directories "renamed" this way, but you can
	     delete it and a plain "update" won't bring it back.


	2. Move the files and directories in the Repository to the new
	   names.

	   - You save the revision history under a different file name.

	   - You save a little space.

	   - "update -r <tag>" produces the wrong files or directories.

	     This is not a good general solution, but if you plan never to
	     look back (someone may be gaining on you!), it is sometimes a
	     useful notion.

	     If you are clever with Makefiles, you might be able to rework
	     them to handle either the new or old names, depending on
	     which ones exist at the time.  Then you can move an old <tag>
	     onto the new, more sophisticated, revision of the Makefile.
	     (Yes, this changes the "released" file if <tag> indicates a
	     release.  But it is an option.)

	   - Important Note:  If you rename a directory, you must rename
	     the corresponding directory in every checked-out working
	     directory.	 At the same time, you must edit the pathname
	     stored in the ./CVS/Repository file within each of the moved
	     directories.

	     The easiest way to move a lot of directories around is to
	     tell everyone to remove their working directories and check
	     them out again from scratch.

	   - The file exists in the working directory and in the
	     ./CVS/Entries file, but not in the Repository.  For the old
	     file, "update" prints:

		cvs update: xyz.c is no longer in the repository

	     and deletes the file.  If the file was modified, "update"
	     prints:

		cvs update: conflict: xyz.c is modified but
					no longer in the repository
		C xyz.c

	     and leaves the file alone.	 In the new directory, you see:

		U xyz.c

	     as you would if someone else executed "add" and "commit".


	3. For each file, copy the working file to a new name in the
	   working directory and use the "cvs remove" to get rid of the
	   old old file and "cvs add" to add the new one.  Since there is
	   no way for CVS to remove a directory, this only works for files.

	   - This is what most people think of first.  Without a "rename"
	     command, the remove/add technique seems obvious.

	   - You lose the connection of your new working file to its past
	     revision history.


 4B.9	What are "Attic" directories?

	When you use the "remove" command on a file, CVS doesn't delete
	the file, it only registers your desire to delete it.

	When you "commit" a removed file, CVS moves the Repository's
	matching RCS file into a sub-directory named "Attic" within the
	Repository.

	Attic files are examined when the '-r' or '-D' option is used
	on "checkout" or "update".  If the specified revision, tag or
	date matches one on a file in the Attic, that file is checked out
	with the others.

	You can think of the Attic as a sort of dead branch, which is only
	looked at when you refer to a <tag> or <date>.


 4B.10	Is it OK to remove anything from the Repository?

	In general, removing anything from the Repository is a bad idea.
	The information in a deleted object is lost forever.  There are
	many ways to skip over files, directories and revisions without
	deleting them.

	Here are some of the consequences of removing the following things
	stored in the Repository:

	1. CVSROOT files  (Repository control files)

	   The Repository will work without any of them, but you should
	   understand what you are losing by deleting them.  See 4B.2.

	2. Revisions

	   The only way to remove revisions is to use the "admin -o"
	   command (or the equivalent RCS command "rcs -o").

	   They are lost forever.  Any tags formerly attached to deleted
	   revisions are now pointing into the Phantom Zone.  You'll need
	   to contact Jor-el to get them back.

	3. Files

	   You should not remove a file unless you truly never want to see
	   it again.  If you want to be able to check out an old revision
	   of this file, use "cvs remove" instead.

	4. Tags

	   Tags take up little space and you can't recover from deleting
	   them.  If you depend on tags for releases you will lose vital
	   information.

	5. Directories

	   There is no Attic for directories, so the only way to remove
	   them is to use "rm -r".  They are gone forever.

	   If you delete (or move) a directory, all checked-out versions
	   of that directory will cause CVS to halt.  You'll have to visit
	   each checked-out directory and remove the matching working
	   directory by hand.

	6. Attic files

	   The "remove" command sends files to the Attic.  To really
	   delete them, you have to go into the Attic and use "rm".

	   If a file in the Attic has a Tag on it that you might ever want
	   to check out again, you probably don't want to delete it.

	7. Lock files (named: "#cvs.[wr]fl.<pid>")

	   These are lock files.  If you are getting "lock" errors and
	   the dates on the lock files indicate that they are old, you can
	   delete them.

	   Deleting lock files still in use by a CVS process might produce
	   unusual errors.


 4B.11	Can I convert to CVS from RCS without losing my revision history?

	Yes, you can simply move (or copy) your RCS files into a directory
	within the Repository, check out that directory and start working.


 4B.12	Can I move RCS files with branches in them into the Repository?

	Yes, but they may not work if you created branches in a way that
	conflicts with CVS's assumptions:

	1. You can't use .0. branches.	(They are reserved for "Magic"
	   branch tags.)

	2. If you use branch 1.1.1, you can't use the Vendor branch.

	You can use other RCS branches under CVS.  There is no need to
	create "magic" branch tags because the physical branch already
	exists.


 4B.13	Can I use raw RCS commands on the Repository?

	You can use raw rcs commands directly on the Repository if you
	take a little care.  The Repository itself contains no "CVS state"
	(as opposed to RCS revision histories) outside the CVSROOT
	directory.

	But using raw RCS commands to change branches, tags or other
	things that CVS depends on may render the files unusable.

	See 4D.7 on RCS/CVS sharing of the Repository and Section 3B on
	the "admin" command.


 4B.14	How do I convert from SCCS to RCS?

	You'll have to execute something like "sccs2rcs" (in the CVS
	contrib directory) on every file.  Then you can move the resulting
	RCS files into the Repository as described above.


 4B.15	How do I limit access to the Repository?

	There are all sorts of ways to restrict access to Repository
	files, none of which are hooked directly into CVS.

	Techniques for limiting access include:

	1. Training, management and good backups.

	   The best form of Repository control is a combination of:

		- A reliable backup scheme (verify it!)
		- Enough training to ensure your developers are competent
		  and knowledgeable about all areas of your sources.
		- Effective management of the boundaries and grey areas.

	   In many cases, technical solutions to "security" problems are
	   inadequate.	You should first try to avoid them.

	   Personal Opinion: In an environment where "unknowns" are
	   allowed to touch important sources the "owner" of the CVS
	   Repository must be a large, loud, vigorous lout with a
	   well-balanced truncheon and the right to use it.  Don't
	   underestimate the effectiveness of letting everyone know they
	   will be strapped into the stocks on the Town Common and pelted
	   with vegetables if they break something they don't understand
	   without first asking the experts.

	2. Set Unix groups and permissions.  See 4B.5.
	   You can set different owners, groups and permissions for each
	   sub-directory within the Repository if that helps.

	3. Catch invocations of "commit" by defining pre-commit programs
	   in the "commitinfo" file.  This is fairly powerful, since it
	   can block commits based on anything you can program.	 Take a
	   look at the programs in the "contrib" directory of the CVS
	   source tree.

	4. Use multiple Repositories, each with its own protection scheme.
	   If you use NFS (or AFS) you can even use "export" restrictions
	   to various groups of machines to keep (for example) the
	   Engineering Repository off the Customer Service machines.

	5. Try the "setgid" trick described in 4D.13.

	6. Try to use the RCS access control lists, though I don't
	   think CVS will handle them cleanly.

	7. Edit the source code to CVS to add your own access control.


 4B.16	What are the Repository Administrator's responsibilities?

	Generally, the Administrator should set "policy", create the
	Repository and monitor its size and control files.

	Some specific responsibilities include:

	1. Examining the Repository once in a while to clean up:

	   a. Trash files left by misguided developers who mistake the
	      Repository for a working directory.

	   b. Non-RCS files.  Other than the files CVS needs in the
	      $CVSROOT/CVSROOT directory, every file in the Repository
	      should be an RCS file.

	   c. Lock files (both CVS '#*' and RCS ',*' files) left around
	      after crashes.

	   d. Wrong permissions, groups and ownerships.

	   e. Locked files. (RCS locks, that is.)

	   f. Attic files that should never have been under CVS at all.
	      Don't blindly delete files from Attic directories -- they
	      were mostly put there (via the "cvs remove") for a reason.
	      Files that should be deleted are binary files (e.g. '*.o',
	      'core', executables) that were mistakenly inserted by
	      "import -I !".

	2. Maintaining the modules file.

	3. Storing site-specific ignore patterns in the
	   $CVSROOT/CVSROOT/cvsignore file.

	4. Storing the names of non-standard CVSROOT files (See 4B.2) in
	   the $CVSROOT/CVSROOT/checkoutlist

	5. Maintaining the other Repository control files: commitinfo,
	   loginfo, rcsinfo and editinfo.

	6. Pruning the history file every once in a while.  (Try the
	   "cln_hist.pl" script in the "contrib" directory.)

	7. Staying aware of developments on the info-cvs mailing list and
	   what is available in the FTP and WWW archives.

	8. Running "ps ax" once in a while and kill off any "update"
	   programs not running as "root".  It is too easy to leave the
	   "cvs" off the front of the "cvs update" command.

	9. Executing monitor programs to check the internal consistency of
	   the Repository files.  Ideas:

	   a. Files that have a default RCS branch that is not 1.1.1
	      (From an abuse of "admin -b".)

	   b. Files that have only Revisions 1.1 and 1.1.1.1, with a
	      default branch of "MAIN".	 (From an abuse of "admin -o".)

	   c. Existing branch tags and various branch consistency checks.


 4B.17	How do I move the whole Repository?

	Copy or move the tree.	(On Unix systems, a set of piped "tar"
	commands works great.  If the Repository does not contain any
	symlinks, which it normally doesn't, you can also use "cp -r".)

	If you can avoid changing $CVSROOT (i.e. the "logical" pathname of
	the Repository) by replacing the old location with a symbolic link
	to the new location, you don't have to do anything else.

	(You could also mount the new location on top of the old location
	if you are using NFS or some other filesystem that allows it.)


	If you must change $CVSROOT, you must also tell everyone to change
	the CVSROOT environment variable in all running shells and in any
	personal configuration files ('.' files on Unix) where it is set.

	The Repository itself contains no references to its own name,
	except possibly in some of the files in the CVSROOT directory.	If
	your modules (or loginfo, commitinfo, etc.) file mentions helper
	programs directly in the Repository, you'll have to change the
	pathnames to point to the new Repository location.

	The main changes you'll have to make are to all the CVS
	administrative files (./CVS/Repository and ./CVS/Root) in every
	working directory ever checked out from the previous location of
	the Repository you just moved.

	You have three choices:

	1. If all ./CVS/Repository files in all working directories
	   contain relative pathnames, you don't have to do anything else.

	2. Have everyone "release" or delete their working directories
	   (after committing, or just saving, their work) and check them
	   all out again from the new Repository after the move.

	3. Use "find . ( -name Repository -o -name Root )" and a
	   PERL or shell script to run through all the ./CVS/Repository
	   and ./CVS/Root files and edit the values in the files.


 4B.18	How do I change permissions on a file in the Repository by using
	a CVS command?	(i.e. without using "chmod 777 $CVSROOT/dir/file")

	When you first "import" or "add"/"commit" a file, the read and
	execute bits on the Repository file are inherited from the
	original source file, while the write bits on the Repository file
	are are turned off.  This is a standard RCS action.

	After that, there is no way to alter the permissions on a file in
	the Repository using CVS (or RCS) commands.  You have to change
	the permissions on both your working file and on the Repository
	file from which it was retrieved.

	Whenever you "checkout" the file or retrieve a new revision via
	"update" (or after a "commit"), your working file is set to match
	the permissions of the Repository file, minus any "umask" bits you
	have set.



----------------
-- Section 4C --	Branching and Merging
----------------

 **** Questions:

 4C.1	What is a branch?
 4C.2	Why (or when) would I want to create a branch?
 4C.3	How do I create and checkout a branch?
 4C.4	Once created, how do I manage a branch?
 4C.5	Are there any extra issues in managing multiple branches?
 4C.6	How do I merge a whole branch back into the trunk?
=4C.7	How do I merge changes from the trunk into my branch or between
	branches?
 4C.8	How do I merge onto the Main Branch a file that exists only on a
	branch other than the Main Branch?  (i.e. it is in the Attic)
 4C.9	How do I know what branch I'm (working) on?
 4C.10	Do I really have to know the name of the branch I'm working on?
 4C.11	How do I refer to the revision where I branched so I can see
	what changed since the Branch Point on another branch?
 4C.12	Why didn't the command "cvs admin -bBRANCH1 *" create a branch?
 4C.13	Is it possible to set the "default CVS branch" for everyone?
 4C.14	How do I perform a large merge?
 4C.15	Is a Vendor merge any different from a branch merge?
 4C.16	How do I go back to a previous version of the code on a branch?
 4C.17	Once I've found the files I want, how do I start changing them?
	I keep getting warnings about sticky tags.
 4C.18	Why do I get the latest files on the branch when I tried to
	"update -r <tag>"?
 4C.19	How can I avoid a merge?  I just want to move the latest revision
	on my working branch directly onto the trunk.
 4C.20	How to I avoid merge collisions in the RCS $\Log$ data?
 4C.21	Why should I trust automatic merges?
 4C.22	How does CVS decide if it can safely perform a merge?
 4C.23	After resolving merge conflicts in a file, what if I want to keep
	my previous version, and not take any of the branch changes?


 **** Answers:

 4C.1	What is a branch?

	Unfortunately, the word "branch" is an overloaded technical term.
	It is used in too many different ways in three categories.  It
	might help to understand some of the issues by going through
	the categories:

	1. How Humans use the word "branch":

	   Most development starts with everyone working on the same
	   software, making changes and heading toward a single goal.
	   This is called something like "Main Line Development".  Note
	   that though many people do main line development on CVS's
	   "Main Branch", that is a choice, not a requirement.

	   After a release or when one or more developers want to go off
	   and work on some project for a while, the Software Engineers
	   assigned to deal with large software issues generate a "Branch
	   in Development" to support the release or project.  (Keep in
	   mind that a programmer is no more a Software Engineer than a
	   carpenter is a Civil Engineer.)

	   Essentially, the word "branch" implies a way to allow
	   simultaneous development on the same files by multiple people.

	   The above terms are human-oriented.	They refer to actions
	   that people would like to take.  They do *not* imply any
	   particular implementation or set of procedures.  Branches in
	   development can be supported in many different ways.


	2. How CVS uses the word "branch":

	   CVS uses the word "branch" in a number of ways.  The two most
	   important are:

	      - The vendor branch holds releases from (normally) an
		outside software vendor.  It is implemented using a
		specific RCS branch (i.e. 1.1.1).

	      - The "Main Branch", which normally holds your "Main Line
		Development", but is defined as the collection of
		revisions you get when you "checkout" something fresh, or
		when you use the '-A' option to "update".

	   Important Note: The CVS "Main Branch" is *not* the same as
	   the RCS concept with the same name.	If you are using Vendor
	   Branches, files you have never changed are on three branches at
	   the same time:

		- The RCS 1.1.1 branch.
		- The CVS Vendor branch.
		- The CVS "Main Branch".

	   The concepts overlap, but they are not equivalent.

	   In referring to CVS, "branch" can be used in four other ways:

	      - A CVS working directory satisfies the definition of
		"branch" for a single developer -- you are on a private
		"virtual branch" that does not appear in any of the RCS
		files or the CVS control files.

	      - The CVS "default branch" is the Repository source for the
		collection of files in your working directory.	It is
		*not* the same as the RCS "default branch".  Normally the
		CVS default branch is the same as the CVS Main branch.	If
		you use the "-r <branch_tag>" option to the "checkout"
		command, you will record a "sticky" tag that changes your
		default branch to the one you checked out.

	      - A "magic" branch can be a branch that hasn't happened
		yet.  It is implemented by a special tag you can check out
		that is not attached to a real RCS branch.  When you
		commit a file to a magic branch, the branch becomes real
		(i.e. a physical RCS branch).

	      - And, of course, CVS uses "branch" to indicate a
		human-oriented "branch in development".

	3. How RCS uses the word "branch":

	   - The RCS "Main Branch" (Synonym: "The Trunk") contains a
	     series of two-part revision numbers separated by a single '.'
	     (e.g. 1.2).  It is treated specially and is the initial
	     default branch.  (The default default?)

	   - The RCS "Default" branch starts out attached to the RCS "Main
	     Branch".  For RCS purposes, it can be changed to point to any
	     branch.  Within CVS, you *must*not* alter the RCS default
	     branch.  It is used to support the CVS idea of a "Main
	     Branch" and it must either point to the RCS Main Branch, or
	     the Vendor Branch (1.1.1) if you haven't made any changes to
	     the file since you executed "import".


 4C.2	Why (or when) would I want to create a branch?

	Remember that you can think of your working directory as a
	"branch for one".  You can consider yourself to be on a branch
	all the time because you can work without interfering with others
	until your project (big or small) is done.

	The four major situations when you should create a branch:

	1. When you expect to take a long time or make a large set of
	   changes that the merging process will be difficult.	Both
	   "long" and "large" are defined in your own environment.

	2. When you want to be able to "commit" and "tag" your work
	   repeatedly without affecting others.

	   If you ever think you need Source Control for your own work,
	   but don't want your changes to affect others, create a private
	   branch.  (Put your username in the branch tag, to make it
	   obvious that it is private.)

	3. When you need to share code among a group of developers, but
	   not the whole development organization working on the files.

	   Rather than trying to share a working directory, you can move
	   onto a branch and share your work with others by "committing"
	   your work onto the branch.  Developers not working on the
	   branch won't see your work unless they switch to your branch or
	   explicitly merge your branch into theirs.

	4. When you need to make minor changes to a released system.

	   Normally a "release" is labeled by a branch tag, allowing later
	   work on the released files.	If the release is labeled by a
	   non-branch tag, it is easy to add a branch tag to a previously
	   tagged module with the "rtag" command.  If the release is not
	   tagged, you made a mistake.	Recovery requires identifying all
	   revisions involved in the release and adding a tag to them.


 4C.3	How do I create and checkout a branch?

	Suggested technique:

	  1. Attach a non-branch tag to all the revisions you want to
	     branch from. (i.e. the branch point revisions)

	  2. When you decide you really need a branch, attach a branch tag
	     to the same revisions marked by the non-branch tag.

	  3. "Checkout" or "update" your working directory onto the branch.


	A. Suggested procedure when using modules:

	   1. cvs rtag <branch_point_tag> module
	   2. cvs rtag -b -r <branch_point_tag> <branch_tag> <module>
	   3. cvs checkout -r <branch_tag> module


	B. Suggested procedure when using your working directory, which
	   contains the revisions of your working files you want to branch
	   from:

	   1. cvs tag <branch_point_tag>
	   2. cvs rtag -b -r <branch_point_tag> <branch_tag> <module>
	   3. cvs update -r <branch_tag>


	In each procedure above, Step #1 applies a non-branch tag to all
	the branch point revisions in the module/directory.  Though this
	is not strictly necessary, if you don't add a non-branch tag to
	the revisions you branch from, you won't be able to refer to the
	branch point in the future.

	Between steps 1 & 2 you may commit changes.  The result would be
	same because "rtag -r <oldtag> <newtag>" applies <newtag> to the
	same revision that <oldtag> is attached to.  You can use this
	technique to avoid attaching *any* branch tags until you need
	them.

	Step B.2 has two corollaries:

	  1. If you plan to create the branch tag before committing
	     anything in your working directory, you can use "cvs tag -b
	     <branch_tag>" instead of the "rtag" command.

	  2. The <module> can be a relative path to a directory
	     from which your working directory was checked out.

	     If you have trouble figuring out what <module> to use (or
	     pathname to use in its place), you can aim it at whatever
	     parent directories you believe will cover all your work.

	     If you are sure the <branch_tag> is not being used anywhere
	     else, you can even aim it at the whole Repository ($CVSROOT),
	     if you have to.  It might take some extra time, but assuming
	     that your <tag> is a unique string and you don't use the '-f'
	     option to "rtag -r", "rtag" will only add a <tag> to files in
	     which it actually *finds* the earlier <tag>.

	In each procedure above, Step #3 may occur any time after step 2.
	Unless you explicitly remove them with "tag -d", a  <tag> is
	permanent.


	The <branch_tag> is an unusual creature.  It labels a branch in a
	way that allows you to "checkout" the branch, to "commit" files to
	the end of the branch and to refer to the end of the branch.  It
	does not label the base of the branch (the branch point).

	There are two obvious ways to choose the <branch_point_tag> and
	<branch_tag> names.  But keep in mind that the <branch_tag> is
	typed by any developer who wants to work on the branch -- you
	should make it mean something to them.

	Style #1 presumes that the simple version string refers to a set
	of designed, documented or promised features, not to a specific
	set of files.  In this case, you tag the branch with the generic
	Version string and assume that whenever you refer to "Version",
	you want the "latest" set of files associated with that Version,
	including all patches.	(You can substitute whatever you like for
	"bp_", as long as your <branch_point_tag> is some modification of
	the <branch_tag>.)

		<branch_point_tag>	Matching <branch_tag>

		bp_V1_3			V1_3
		bp_Release2-3-5		Release2-3-5
		bp_Production4_5	Release4_5


	Style #2 presumes that the simple version string refers to the
	specific set of files used to construct the first release of
	"version".  In this case, you tag the branch-point revisions with
	the generic Version string and assume that whenever you refer to
	this Version, you want the original set of released revisions.	To
	get the latest patched revisions of the release, you refer to the
	branch tag "latest_<branch_point_tag>". (You can substitute what
	ever you like for "latest_", as long as your <branch_tag> is some
	modification of the <branch_point_tag>.)

		<branch_point_tag>	Matching <branch_tag>

		V1_3			latest_V1_3
		Release2-3-5		latest_Release2-3-5
		Release4_5		latest_Production4_5


	In both styles you can find out what you had to change since the
	original release of this Version by typing:

	    cvs diff -r <branch_point_tag> -r <branch_tag>

	For Style 1, this is:

	    cvs diff -r bp_<branch_tag> -r <branch_tag>

	For Style 2, this is:

	    cvs diff -r <branch_point_tag> -r latest_<branch_point_tag>


	Notes on "being on a branch":

	- "update -r <tag>" tells CVS to attach a "sticky tag" to
	  working directory (in ./CVS/Tag) and the checked-out files (on
	  each line of ./CVS/Entries).

	- A "sticky" <tag> (including a <branch_tag>) causes most CVS
	  commands to act as if "-r <tag>" were on the command line.

	- A "sticky" <branch_tag> indicates that the working directory
	  (and working files) are "on the branch".


 4C.4	Once created, how do I manage a branch?

	The most important thing you should know about managing a branch
	is that the creation of a branch is not a lightweight act.  When
	you create a branch, you must also create a set of procedures to
	keep track of it.

	Specifically, you must:

	- Remember that the branch exists.  (This is non-trivial if you
	  create a lot of them.)

	- Plan when to merge it back into the main line of development.

	- Schedule the order that multiple branch merges are to be done.

	- If you ever intend to merge branches into each other, instead of
	  limiting merges of branch work back into the "main line", you
	  must keep careful track of which parts of which branches have
	  merged into which other branches.


	The simplest way to deal with branches is to limit their number,
	"collapse" them back into the main line as quickly as is
	reasonable and forget them.  If a group wants to continue working,
	tell them to create another branch off the fully merged main line.

	Remember that CVS is just a tool.  Over time, it will probably
	handle branching better, requiring less careful attendance.
	But no matter how good it becomes, the whole idea of "branching"
	is a complicated management problem.  Don't take it lightly.


 4C.5	Are there any extra issues in managing multiple branches?

	If you plan to split from the "main line" and merge back after a
	time, the only problem will be scheduling the order of branch
	merges.	 As each branch is merged, the main line must be rebuilt
	and tested.  Merging multiple branches (i.e. "lines of
	development") before building and testing creates more problems
	than you are ready for.

	If you plan to collapse some branches into others, then move the
	combined branches back into the main line, you have to be careful
	with the revisions and tags you hand to your "update -j"
	command, but it shouldn't be much trouble.

	If you plan to allow every branch to incrementally take the work
	done on other branches, you are creating an almost insurmountable
	bookkeeping problem.  Every developer will say "Hey, I can
	handle taking just this little bit," but for the system as a
	whole it is disaster.  Try it once and see.  If you are forced
	into this situation, you will need to keep track of the beginning
	and end points of every merge ever done.  Good Luck.


 4C.6	How do I merge a whole branch back into the trunk?

	If you don't have a working directory, you can checkout and merge
	in one command:

		cvs checkout -j <branch_tag> <module>
		cd <module>

	If you already have a working directory:

		cd <working_directory>
		cvs update	<== Optional, to bring it up to date.
		cvs update -j <branch_tag>

	CVS will print lines beginning with

	'U'	for files that you hadn't changed, but the branch did.

	'M'	for files that you changed and the branch didn't
		*and* for files that you both changed that were merged
		without overlaps.  (This overload is unfortunate.)

	'C'	for files that you both changed in a way that conflicts
		with each other.

	You need to go edit all the 'C' files and clean up the conflicts.
	Then you must commit them.


=4C.7	How do I merge changes from the trunk into my branch or between
	branches?

	The idea is similar to the above, but since CVS doesn't treat the
	main branch like other branches, you'll have to be more careful.
	There are 5 different ways to look at the problem.

	A. The way to merge *all* changes made on the trunk into a working
	   branch is to move to the branch you want via "checkout -r" or
	   "update -r":

		cvs update -r <branch_tag> {optional files}

	   Then merge the changes from the trunk into your working branch
	   using the pseudo-tag named "HEAD":

		cvs up -j HEAD {optional files}

	   You will get everything from the branch point of the branch
	   named <branch_tag> up to the HEAD of the main branch.  This is
	   still kind of strange.  If the file is on a branch, HEAD should
	   be the latest thing on the branch, not the HEAD of MAIN.  But
	   that's not the way CVS (currently) works.

	   If you run "cvs up -j HEAD" again after adding more revisions
	   to the trunk, you may get overlaps for the text you have
	   already merged.  It depends on your version of your RCS "merge"
	   command (actually the "co -j" option, which depends on the
	   version of "diff3" you configured RCS to use).


	B. You can merge the difference between any two <tags> using
	   two "-j" options on "update" or "checkout".

	   Identify the two tags on the branch you want to merge from.

		cvs update -j <tag1> -j <tag2> {optional files}

	   This step assumes you were careful about tagging milestones.
	   You can use this technique for any two <tags> on the same
	   branch, even the trunk.  It is also possible to use tags on
	   different branches, but you'll have to ponder the meaning of
	   the difference between those two tags.

	   In place of one of the <tags>, you can use a <branch_tag> to
	   refer to the latest revision on that branch.  See 4C.11 and
	   4C.3 for info on branch points.

	   Merges can also be performed by handing RCS revisions to the
	   '-j' options, but since revision numbers aren't the same in all
	   files, merging by number is normally limited to one file.  Sets
	   of files with the exact same trees of branches and revision
	   numbers would work too, but that's a rare situation.


        C. To "take" revisions from other branches instead of merging
	   them, see 4C.19 for an idea.


	D. A way to gain the effect of merging the main to the branch is
	   to merge the branch into the main using the normal

		cvs update -A {optional files}
		cvs update -j <branch_tag> {optional files}
		cvs commit
		cvs tag -F  -b <same_branch_tag> {optional files}

	   See part B of 4D.5

	
	E. Other oddities.

	   This also works, but is probably not officially supported:
	   
		   cvs update -j N {optional files}
	   
	   where N is a number.  This will merge all the changes from the
	   branch point up to the highest revision on the main branch
	   starting with N.  For example, if your highest trunk revision
	   is 1.52, you can use this to grab revisions from the trunk:
	   
		   cvs update -j 1 {optional files}
	   
	   Another example: Say you have a branch point at rev 1.2 for a
	   branch named "BR1" and trunk revisions 1.3, 1.4, 2.1, 2.2, 2.3,
	   3.1, 3.2.  Then:
	   
		   cvs update -j 1 {optional files}
	   
	   will merge the changes from 1.2 to 1.4
	   
		   cvs update -j 2 {optional files}
	   
	   will merge the changes from 1.2 to 2.3
	   
		   cvs update -j 3 {optional files}
	   
	   will merge the changes from 1.2 to 3.2, which in this example, is
	   equivalent to the use of "-j HEAD" in part A above.
	   
	   The intuitive (at least to me):
	   
		   cvs up -j MAIN (or TRUNK) {optional files}
	   
	   doesn't work.  If the trunk (i.e. "main branch") had an
	   implicit branch named "MAIN", you could use:
	   
		   cvs up -j MAIN:10/26 -j MAIN:now {optional files}
	   
	   and refer to date-stamped revisions on the trunk using the
	   <branch_tag>:<date> support that works on other branches.
	   
	   You might also think you could place an explicit tag on branch
	   1 (or higher) (e.g. MAINHACK:1) and use it in place of the
	   implicit "MAIN", but I haven't found the right combination.
	   
	   [[If you find working techniques, I'll add them here.]]


 4C.8	How do I merge onto the Main Branch a file that exists only on a
	branch other than the Main Branch?  (i.e. it is in the Attic)

	For how such a file can exist, see 3A.2 and 3A.3.

	For how to avoid creating such a file, see 3A.5.

	Though you might think that the "update -j" command could perform
	the "merge" of a file from the side branch to the Main Branch, it
	isn't (yet) smart enough.  Unfortunately, there is no single CVS
	command to do this -- it takes three steps:

	1. To move something onto the Main Branch from the Attic, you have
	   to physically move the file from the Attic to the main
	   Repository directory associated with your working directory.

	   It is exactly like resurrecting a removed file.  See 3L.4

	   I use something like this: (csh-like syntax)

		set repos = `cat ./CVS/Repository`
		mv $repos/Attic/filename,v $repos/filename,v

	   (If you use relative paths in your Repository files, that first
	    line becomes: set repos = $CVSROOT/`cat ./CVS/Repository`)

	2. Now that the file is physically in the right place within the
	   Repository, "update -A" will make it appear in your working
	   directory on the Main Branch.  Do that now.

	3. You now have a choice.  The act of physically moving the file
	   has fused together the <branch_tag> branch and the Main Branch
	   for this file.  You can continue that way, making changes along
	   the RCS Main Branch which CVS will (for this type of file only)
	   treat as both the Main Branch and the <branch_tag> branch.

	   The other choice, which I would suggest, is to re-tag the file
	   with <branch_tag>, restoring a normal-looking magic branch tag
	   to the file:

		cvs tag -F -b <branch_tag> <file>


	After you have done the above, you can run "update -A" or "update
	-r <branch_tag>" to resume whatever you were doing before you
	started this procedure.

	Caveat: The final result is a file whose revision tree doesn't
	look like it was ever on any branch but the Main Branch until the
	above "tag -F -b" command was executed.	 CVS and RCS have no way
	of saving the history of the actions you have just performed.


 4C.9	How do I know what branch I'm (working) on?

	Type:
		cvs status

	and look at the "Sticky Tag" field for each file.  If:

	1. The *same* tag is on *every* file in your working tree, *and*
	2. That tag matches the contents of the ./CVS/Tag file, *and*
	3. That tag is a branch tag,

	then you know what branch you are working on.  You can get sticky
	Tag information directly from the ./CVS/Entries file instead of
	"cvs status".

	If all the sticky Tags don't agree, then your directory is
	temporarily inconsistent.  This is a feature allowing you to make
	changes (or perform merges) to individual files on multiple
	branches without checking out the whole directory.

	The sticky Tag on each file in the ./CVS/Entries file (as
	displayed by the "status" command) indicates what branch the
	working file is on.  New files are added to the Tag stored
	in ./CVS/Tag.

	To force your entire working directory onto the same branch, type:

		cvs update -r <branch_tag>


 4C.10	Do I really have to know the name of the branch I'm working on?

	If a developer can't be relied on to know what branch of
	development to work on, then either the developer's manager
	isn't planning branches properly or the developer has serious
	problems.

	I have found that one of the hardest concepts to get across to
	developers (and some managers) is that "a branch in development"
	(as opposed to the use of RCS branches to support some other
	scheme) is a heavyweight act.  Every time you create a real branch
	in development, you must spawn a set of managerial procedures and
	a schedule by which you plan to merge each branch into each other
	branch.	 Unless you plan to keep it simple and collapse (by
	merging and forgetting) branches quickly, they are not to be
	created lightly.

	In other words, if you don't regularly attend group meetings in
	which the branch to be worked on is a major topic of discussion,
	then the group is not managing branches properly.

	We created a couple major branches a few months ago and even the
	customer service people refer to the "XYZ branch" as a shorthand
	for "continuing development on the XYZ project".


 4C.11	How do I refer to the revision where I branched so I can see
	what changed since the Branch Point on another branch?

	Given the current <branch_tag> format, there is no direct way to
	refer to the branch point, which is more useful in many ways
	than referring to the branch, which always refers to the latest
	revision on the branch.

	When CVS adds a branch tag, it attaches an RCS symbol to a
	non-existent revision number containing the revision number of the
	branch point as a prefix.  (See Section 3O, on the "tag" command.)
	RCS can't use the CVS magic branch tag and many of the CVS
	commands can't refer to it.

	To be certain of your ability to refer to a branch point, you must
	create a "branch point" tag at the same time as the Branch tag.
	See 4C.3.


 4C.12	Why didn't the command "cvs admin -bBRANCH1 *" create a branch?

	Because your command creates an RCS branch, not a CVS branch.  See
	the above discussion on branches.  RCS branches are used to
	support CVS branches, but they are not the same.  You can't act as
	if you have direct control over the RCS files.

	The "admin" command was placed there as a convenience to allow
	you to execute raw "rcs" commands on the Repository, taking
	advantage of CVS's ability to find the files in the Repository.

	But you have to remember that you are using RCS commands on a
	CVS Repository, which is not generally safe unless you know
	exactly what CVS depends on.

	For one thing, CVS insists on control of the default branch.  It
	is set either to the Main branch or the Vendor branch depending
	on whether you have changed the Vendor's code.	If you change
	the default branch, you are monkeying with the internals and
	you will get unexpected results.

	To set your "default CVS branch" to BRANCH1, you must use
	"checkout" or "update" with the "-r BRANCH1" option.  Then you
	have changed CVS's idea of your "default branch", which has
	little to do with RCS's default branch.


 4C.13	Is it possible to set the "default CVS branch" for everyone?

	No.  It doesn't work that way.

	When using CVS, all administrative information (such as what
	branch you checked out) is stored in CVS sub-directories, local to
	the user.  There is no global state, other than the description
	and logging files in the $CVSROOT/CVSROOT directory.

	You tell "checkout" or "update" what branch you want to check out
	via the "-r <tag>" option.  The default is CVS's "Main Branch".

	I don't see a problem in *designing* a new way to indicate what
	branch you get by default, instead of the main one, but that's not
	how it currently works.


 4C.14	How do I perform a large merge?

	Large merges require a bit more planning to be able to track
	what has happened in the inevitable cases where something goes
	wrong.	No tool can force a "merge" to make perfect sense.

	Though you can handle the details in many different ways, the two
	ends of the spectrum of merge techniques are: gonzo and paranoid.

	A. The gonzo method assumes that you know everything about your
	   sources so that recovery from failures is "just a matter of
	   typing."  You created the branch this way:

		cvs checkout <module>
		cd <module>
		cvs tag -b <branch_tag>
		cvs update -r <branch_tag>
		>>> Edit away.
		cvs commit		<<== Onto branch

	   Now you want to merge your branch back into the Main branch,
	   you are certain you can make it work, or at least detect all
	   the failures, so you dive in and hack away: (For simplicity, we
	   will assume you are collapsing (i.e. merging and forgetting) a
	   side-branch into the Main branch from your single working
	   directory.)

		cvs update -A
		cvs update -j <branch_tag>
		>>> Edit the 'C' files and remove the overlaps.
		>>> Edit some more to make it all compile and work.
		cvs commit

	   Looks simple.  For more details on the output from the
	   "update -j" command, see 3P.2 and 4C.6.

	   Note: You could also checkout a whole new working directory and
		 perform the merge at the same time by replacing the two
		 update commands with these two commands:

			cvs checkout -j <branch_tag> <module>
			cd <module>


	B. The paranoid way is more difficult, but it can catch all sorts
	   of problems.	 You created the branch this way:

		cvs checkout <module>
		cd <module>
		cvs tag <branch_point_tag>
		cvs tag -b <branch_tag>
		cvs update -r <branch_tag>
		>>> Edit away.
		cvs commit		<<== Onto branch

	   The extra tag command places a non-branch tag on the Branch
	   Point, an act that makes it easier to do "diffs" later.  Now we
	   decide to perform the merge:

		cvs tag <latest_on_branch_tag>
		cvs update -A
	   *1*	cvs diff -r <branch_point_tag> -r <latest_on_branch_tag>
		>>> *1* shows all the changes on the branch.
	   *2*	cvs diff -r <branch_point_tag> -r HEAD
		>>> *2* shows the changes on the trunk since branching.
		cvs tag <premerge_tag>
		cvs update -j <branch_tag>
		>>> Edit the 'C' files and remove the overlaps.
	   *3*	cvs diff
		>>> Verify that *3* matches *1*, except for line numbers.
		cvs commit
		cvs tag <just_merge_changes_tag>
		>>> Edit some more to make it all compile and work.
		cvs commit
		cvs tag <after_merge_cleanup_tag>


	The reason *3* and *1* match so closely is that they are the
	differences between two pairs of starting points and ending points
	after the same data was inserted.  If they are significantly
	different, you will want to figure out why.

	NOTE: You will have to tell everyone to stay the hell out of the
	Repository while you do this.  If they commit something while you
	are in the middle of a merge, your job will be much more
	difficult.  If they "update" at the wrong time, their work will
	be randomized until you finish.	 It's better to call a halt.

	See 3H.13 for some more information about dealing with merges
	after import.  The last part of the procedure is applicable to any
	large merge.


 4C.15	Is a Vendor merge any different from a branch merge?

	No.  In most ways, a Vendor branch is exactly the same as any
	other branch.  In a Vendor merge, the data is append to the branch
	by the "import" command, rather than by hand-editing, but the
	merge process is the same.

	See the "import" command in section 3H.


 4C.16	How do I go back to a previous version of the code on a branch?

	You can avoid digging into RCS revision numbers (executing "update
	-r <rev>" on each file) by trying one of these:

	1. Use non-branch tags as you normally would.  Non-branch tags
	   attach to specific revisions, so a "tag <tag>" command would
	   mark the revisions you have in your working directory, which
	   are on your branch.	If you need to retrieve them, use "update
	   -r <non-branch-tag>"

	   Doing this overrides the sticky <branch_tag> attached to your
	   working directory with a non-branch tag, which means you won't
	   be able to commit until you again move forward to the end of
	   the branch with "update -r <branch_tag>".

	2. Use the "update -r <branch_tag>:<date>" trick.

	   This is almost like using the '-D' option, but it looks for
	   revisions extant on <date> only along the given branch.

	   As in #1, you can't commit to this kind of working area,
	   because it has a sticky date referring to revisions in the
	   middle of a branch.


	3. You can branch a branch.

	   If you add a branch tag to file in a working directory that was
	   checked out on a branch, you will branch the branch.	 This
	   works just fine, though you'll have to play some games to merge
	   everything back together again.  You'll also create 6-part
	   revision numbers.  (They'll be 8-part revision numbers if you
	   branch a branch that started out with some unmodified files on
	   the Vendor branch.  Think about it.	How does revision
	   1.2.4.2.4.2.2.1 grab you?)


 4C.17	Once I've found the files I want, how do I start changing them?
	I keep getting warnings about sticky tags.

	What you probably did was type "cvs update -r <tag>" where <tag>
	is a non-branch tag.  "update" created a sticky tag for a specific
	revision, not a branch.	 To start working right there, you have to
	create a branch to work on.

	You have two choices.

	A. You can do it in place and keep working:

	   cvs tag -b <branch_tag>	<<== To tag the current files.
	   cvs update -r <branch_tab>	<<== To move onto the branch.

	B. You can do it "externally" and create a new working directory:

	   cvs rtag -b -r <tag> <branch_tag> <module>
	   cvs checkout -r <branch_tag> <module>

	   <module> can be a relative path within the Repository.

	   <tag> in the above is the non-branch tag you placed earlier
		 that caused the error in your question.  Be warned that
		 if <tag> is not set on all the files (or all the right
		 revisions) you won't get exactly what you wanted.


 4C.18	Why do I get the latest files on the branch when I tried to
	"update -r <tag>"?

	If "update -r <tag>" always retrieves the latest files on a
	branch, then <tag> is really a <branch_tag>.  A branch tag is
	supposed to be used to grab a branch to work on.  Since you can't
	modify a file in the middle of a branch, checking out a
	<branch_tag> will give you the latest revision on the branch.

	If you want to "checkout" a specific collection of revisions, you
	must use a "non-branch" tag.  See the first part of 4C.16.


 4C.19	How can I avoid a merge?  I just want to move the latest revision
	on my working branch directly onto the trunk.

	There is no direct way to do this using CVS, though the technique
	is not difficult using shell commands.	Here's one way:

	1. Move your working directory to the Main Branch.

		cvs update -A

	2. Use "update -p" to grab the latest revision on the branch and
	   write it over your working files.  Make sure you don't have an
	   modified files -- you will lose them.  The following is in
	   "csh" syntax.  Change the wildcard to grab the files you want

		foreach i (Makefile *.cc *.hh)
		    cvs update -p -r <branch_tag> $i > $i
		end

	3. Commit all the working files onto the Main Branch.

		cvs commit -m 'Moved branch <branch_tag> onto MAIN'

	You should experiment with the above before blasting everything.


 4C.20	How to I avoid merge collisions in the RCS $\Log$ data?

	In short, you can't.  The RCS $\Log$ keyword is handled
	differently from all other RCS keywords.

	On the info-cvs mailing list, there is a periodic discussion that
	goes something like this:

	  Question: How do I deal with $\Log$?
	   Answer1: You can't do much with it.	Here's how it works. . .
	   Answer2: I've found a limited way to use it. . .
	   Answer3: Get rid of it.  $\Log$ is an abomination.

	I tend to lean toward answer #3.  There are only two sets of
	people who would ever have access to logs stored within sources
	files, developers and source customers.

	For developers:

	1. Log entries within sources files are notoriously incomplete,
	   rushed, poorly phrased and in many cases incorrect, making them
	   useless for debugging or file maintenance.  I remember a maxim
	   from "Software Tools" (I believe): "Read the code, not the
	   comments."  No managerial order or plan for programmer
	   discipline will affect this in the real world.

	2. Log entries are usually in an unreadable mixture of styles.
	   Many log entries are just plain meaningless.	 Some are foolish.
	   Some are even insulting.  Examples:

		"Corrected spelling of misspelling."
		"Bug fix."
		"Reversed stupid change in previous revisions."
		"If Joe could do his job, this would already have worked."

	3. Log entries are not managed well by the tools.  Any merge can
	   cause conflicts in the $\Log$ data.	Branch merges produce
	   incomplete logs.  They can be edited into chaos and they are
	   not regenerated.  They waste space duplicating information
	   available to the developer with a single command.

	4. Even if correct when originally entered, as changes are made to
	   the file, log entries become false over time.  Humans are not
	   good at reading down through a list and remembering only the
	   last change affecting something.  Over time *most* of the log
	   is wrong.

	5. Even if still correct, the log data is almost useless to
	   developers without the code diffs.  If you can get code diffs,
	   you can display the log.


	For source customers the problem is even worse.	 The last thing
	you want to show customers is a hodge-podge of tiny comments about
	large changes followed by a series of emergency fixes before
	delivery.  If you distribute sources, then you should provide
	documentation, or changelogs reviewed by people who won't let
	comments like "Fixed for stupid customer." out the door.

	Conclusion: Though some people would prefer to see in this FAQ
	techniques for making the $\Log$ entries the best they can be, I
	believe them to be a lost cause.  My suggestion is to hunt down,
	root out and destroy all occurrences of $\Log$ and the unusable
	data attached to it wherever you may find it.


 4C.21	Why should I trust automatic merges?

	Some developers have the feeling that three-way merging doesn't
	work.	They fear and distrust the way the "update" command
	automatically merges committed changes from the Repository into
	the working file.

	Experience has shown that most merges are utterly painless and
	most of the rest are easily resolved.  The few conflicts that
	cause headaches are nearly all due to poor communication between
	developers, a problem no source control system can obviate.

	Some developers were troubled in the past by flaky Unix software.
	I can't say that everything is perfect, but the tools CVS depends
	on (RCS and diff, mainly) are fairly solid nowadays.  They work.

	Since it does seem to work for most of us, the algorithm is
	unlikely to change soon.  Why not test it on a couple trouble
	spots and if it works for you, use it for a while?  Then you can
	make an informed decision.


 4C.22	How does CVS decide if it can safely perform a merge?

	CVS can merge any text file, possibly discovering a conflict and
	leaving overlaps for you to edit.  Editing the conflict markers
	out of the file is a moment's work, but resolving the conflict
	could take an arbitrary amount of time.	 CVS works to determine if
	it *should* merge, not if it *can*.

	See 2B.6 for how the merge proceeds.


 4C.23	After resolving merge conflicts in a file, what if I want to keep
	my previous version, and not take any of the branch changes?

	If you want to retain your previous version, a version on the
	MAIN branch greater than 1.1 (one you committed there), just throw
	the merged file away and "cvs update" the file.

	You don't need to commit something to remember it.  The tags you
	place before and after the merge should give all the handles you
	need to find various versions.	You don't have to create a new
	version of the file.

	If you want to retain the previous Vendor revision, you can grab a
	copy of it using "cvs update -p" and commit it or use the
	technique described in 3B.3 to revert back to the Vendor branch.



----------------
-- Section 4D --	Tricks of the Trade
----------------

This section covers topics ranging from simple ideas that occur to every
CVS user to time-saving procedures I consider difficult to understand.

Some are therefore dangerous.  Avoid anything you don't fully understand.


 **** Questions:

 4D.1	How can you even check in binary files, let alone allow CVS to
	do its auto-merge trick on them?
 4D.2	Can I edit the RCS (",v") files in the Repository?
 4D.3	Can I edit the ./CVS/{Entries,Repository,Tag} files?
 4D.4	Someone executed "admin -o" and removed revisions to which
	tags/symbols were attached.  How do I fix them?
 4D.5	How do I move or rename a magic branch tag?
 4D.6	Can I use RCS locally to record my changes without making them
	globally visible by committing them?
 4D.7	How can I allow access to the Repository by both CVS and RCS?
 4D.8	I "updated" a file my friend, "bubba", committed yesterday.
	Why doesn't the file now have a modified date of yesterday?
 4D.9	While in the middle of a large "commit", how do I run other
	commands, like "diff" or "stat" without seeing lock errors?
 4D.10	Where did the ./CVS/Entries.Static file come from?  What is it for?
 4D.11	Why did I get the wrong Repository in the loginfo message?
 4D.12	How do I run CVS setuid so I can only allow access through the
	CVS program itself?
 4D.13	How about using groups and setgid() then?
 4D.14	How do I use the "commitinfo" file?
 4D.15	How do I use the "loginfo" files?
 4D.16	How can I keep people with restrictive umask values from blocking
	access to the Repository?
 4D.17	Why do timestamps sometimes get set to the date of the revision,
	sometimes not?	The inconsistency causes unnecessary recompiles.


 **** Answers:

 4D.1	How can you even check in binary files, let alone allow CVS to
	do its auto-merge trick on them?

	If you configure RCS and CVS to use the GNU version of diff with
	the '-a' option, CVS and RCS will handle binary files.	See
	section 4A for configuration info.

	You may also need to apply the '-ko' flag to the files to avoid
	expanding RCS keywords, which can be done via:

		cvs admin -ko filename


	The only real problem occurs when "cvs update" attempts to merge
	binary revisions committed elsewhere into a modified working file.
	This can be a particular problem if you are trying to use CVS on
	Frame or Interleaf (document processing systems) that produce
	non-text output.

	See 3C.8 for a way to serialize access to binary files.
	See 3A.8 for adding binary files, 3H.4 for importing binary files
	and 3B.4 for some more information about "admin".


 4D.2	Can I edit the RCS (",v") files in the Repository?

	Yes, but be very careful.  The RCS files are not free-form files,
	they have a structure that is easily broken by hand-editing.  The
	only time I would suggest doing this is to recover from emergency
	failures that are difficult to deal with using CVS commands,
	including the "admin" command, which can talk directly to RCS.

	Though no one actively encourages the editing of RCS files, many
	people have succumbed to the urge to do so when pressed for time.
	The reasons given, usually with evident contrition, include:

	- Editing mistakes in, or adding text to, log entries.	(If you
	  have RCS 5.6 or later, you should use `cvs admin -m'.)
	- Renaming or moving symbolic names.  (You should `cvs admin -N'
	  instead.)
	- Unlocking a file by changing the "locker" from someone else to
	  yourself.  (It's safer to use `cvs admin -u -l'.)
	- Making global changes to past history.  Example:  Eradicating
	  former employees names from old documents and Author entries.
	  (And someone thought the "history" command was evidence of Big
	   Brother!  I never realized how much help a wide-open revision
	   control system could have provided to The Ministry of Truth.)


 4D.3	Can I edit the ./CVS/{Entries,Repository,Tag} files?

	Yes, but with CVS 1.3 and later, there is almost no reason to edit
	any of the CVS administrative files.

	If you move pieces of your Repository around it can be faster to
	edit all the ./CVS/Repository files rather than checking out a
	large tree.  But that is nearly the only reason to do so.


 4D.4	Someone executed "admin -o" and removed revisions to which
	tags/symbols were attached.  How do I fix them?

	It depends on what you mean by "fix".  I can think of three ways
	to fix your predicament:


	1. Remove the tags.

	   Assuming you really wanted to get rid of the revision and its
	   associated tags, you can remove them with the "admin" command.
	   The "tag -d" command will only remove tags attached to existing
	   revisions.  You can remove a tag, even if it is attached to a
	   non-existent revision, by typing:

		cvs admin -N<tag> <file>

	2. Retrieve the outdated revision.

	   You should first look in your backup system for recent versions
	   of the file.	 If you can't use them, you can carefully extract
	   each revision that followed the earliest outdated revision
	   using RCS (or "cvs admin") commands and reconstruct the file
	   with all the right revisions, branches and tags.  This is a lot
	   of work.

	   You *can't* insert a revision into the current RCS file.

	3. Move the Tags to another revision in each file.

	   If you want to move the tags to another valid revision, you
	   have two choices, both of which require that you find all the
	   revision numbers of the files you want to "tag" and execute the
	   following command sequences on each <file>.

		a. Use "update" to grab the revision you want, then
		   execute a normal "tag" command to Tag that revision:

			cvs update -r <rev> <file>
			cvs tag <tag> <file>

		b. Use "admin" to set the tag to a specific revision:

			cvs admin -N<tag>:<rev> <file>


 4D.5	How do I move or rename a magic branch tag?

	(To rename a non-branch <tag> see 3O.9.)

	Before reading this, read 3M.3 and 3M.4 and understand exactly
	how tag and rtag use '-r' and why it won't do the right job here.

	A. First, I have to explain exactly what a magic branch tag is.

	   A magic <branch_tag> is an artificial tag attached to a
	   non-existent revision on a non-existent branch number zero.	It
	   looks like this:

		TAG1:<X>.0.Y

	    <X> is the "branch point revision", a normal revision with an
		odd number of '.'s in it. (e.g. 1.5, 1.3.1.6, etc)

	     Y	is an even number (e.g. 2, 4, 6, etc.)	All CVS branches,
		other than the Vendor branch, are even numbered.

	   TAG1 is considered by CVS to be attached to revision <X>.  The
	   first "update -r TAG1 <file>" after applying TAG1 will produce
	   a copy of revision <X> with a sticky tag of TAG1.  The first
	   "commit" to that file will cause CVS to construct an RCS branch
	   named <X>.Y and check in revision <X>.Y.1 on the new branch.

	   Note: TAG1 is *not* considered to be attached to <X> by RCS,
	   which explains why you can't refer directly to the branch point
	   revision for some CVS commands.


	B. Moving a magic <branch_tag> is the act of reapplying the same
	   tag to different revisions in the file:

		TAG1:<X>.0.Y
	   to
		TAG1:<X>.0.Z	or	TAG1:<A>.0.B

	   You can move a magic branch tag to the revisions of your choice
	   by using "update" to find the revisions you want to tag and
	   reapplying the tag to all the files with the '-F' option to
	   force it to move the existing <branch_tag>.

		cvs update -r <tag/rev>	 (or '-A' for the Main Branch)
		cvs tag -F -b <branch_tag>

	   If the earlier location of TAG1 refers to a physical branch
	   within any RCS file, moving it will make the existing branch in
	   the file seem to disappear from CVS's view.	This is not a good
	   idea unless you really want to forget the existence of those
	   RCS branches.

	   If the "update" above retrieves the original branch point
	   revision (<X>), the "tag" command above will create the tag:

		TAG1:<X>.0.Z

	   Where Z is 2 greater than the highest magic branch already on
	   revision <X>.  The TAG1 branch will still have the same branch
	   point (i.e. revision <X>), but the first commit to the new TAG1
	   branch will create a different RCS branch number (<X>.Z instead
	   of <X>.Y).


	C. Renaming a magic <branch_tag> is the act of changing

		TAG1:<X>.0.Y
	   to
		TAG2:<X>.0.Y

	   There is no harm in changing a tag name as long as you forget
	   that TAG1 ever existed and you clean up any working directories
	   with sticky TAG1 tags on them by using "update -A", "update -r
	   <other_tag>" or by removing the working directories.

	   On the other hand, actually changing the tag is not easy.

	   See 3M.3 for why the seemingly obvious solution won't work:

		cvs tag -b -r <old_branch_tag> <new_branch_tag>

	   The only direct way to rename a magic tag is to use the "admin"
	   command on each file:  (You might want to use '-n'.	Read "man
	   rcs" and look at the '-n' and '-N' options.)

		cvs admin -N<new_branch_tag>:<old_branch_tag> .
		cvs tag -d <old_branch_tag>

	   But you have to be careful because "admin" is different from
	   other CVS commands:

	     1. "admin" can be used recursively, but only by specifying
		directory names in its argument list (e.g. '.'),

	     2. Where "rtag -r <old_branch_tag>" would interpret
		<old_branch_tag> as a magic CVS branch tag, "admin" is a
		direct interface to RCS which sees a magic branch tag as
		a simple (though non-existent) RCS revision number.

		This is good for us in this particular case, but different
		from normal CVS.

	     3. "admin" also skips the Attic and produces different kinds
		of errors than CVS usually does.  (Because they are coming
		directly from RCS.)


	   The other way to rename a magic <branch_tag> is to edit the
	   Repository files with a script of some kind.	 I've done it in
	   the past, but I'll leave it as an exercise for the reader.


 4D.6	Can I use RCS locally to record my changes without making them
	globally visible by committing them?

	You can, but it will probably confuse CVS to have ",v" files in
	your working directory.	 And you will lose all your log entries
	when you finally commit it.

	Your best bet is to create your own CVS branch and work there.
	You can commit as many revisions as you want, then merge it back
	into the main line (or parent branch) when you are finished.


 4D.7	How can I allow access to the Repository by both CVS and RCS?

	The first step is to try not to.  If some people are using CVS,
	there is no reason for everyone not to.	 It is not hard to learn
	the basics and CVS makes certain operations *easier* than a series
	of RCS commands.  Personal preference in what software tools can
	be applied to a shared Repository has to take second place to
	system integration needs.  If you disagree, try writing some Lisp
	code for inclusion in your Unix kernel and see what kind of
	reception you get.

	If you really must allow routine RCS access to the CVS Repository,
	you can link an RCS sub-directory into a piece of the Repository:

		ln -s /Repository/some/directory/I/want RCS

	and RCS will work just fine.


	Those who are using RCS will have to keep the following in mind:

	1. If a file was originally added to the Repository by "import"
	   and has not been changed using CVS, the *RCS* default branch
	   will remain attached to the Vendor branch, causing revisions
	   checked-in by "ci" to wind up on the Vendor branch, instead of
	   the main branch.  Only CVS moves the RCS default branch on
	   first commit.

	   The way around this is to checkin (using "ci") all the files
	   first and move them into the Repository.  That way they won't
	   have Vendor branches.  Then RCS will work OK.

	2. It is possible to use "rcs" and "ci" to make the files unusable
	   by CVS.  The same is true of the CVS "admin" command.

	3. Normal RCS practice locks a file on checkout with "co -l".  In
	   such an environment, RCS users should plan to keep survival
	   gear and food for at least 30 days near their desks.	 When
	   faced with bizarre and unexpected permission errors, howling
	   mobs of slavering CVS users will run the RCS users out of town
	   with pitchforks and machetes.

	   See 3C.8 for a way to avoid machetes aroused by lock collisions.

	4. Though files checked in by RCS users will correctly cause
	   "up-to-date" failures during CVS "commits" and they will be
	   auto-merged into CVS working directories during "update", the
	   opposite won't happen.

	   RCS users will get no warning and will not be required to merge
	   older work into their code.	They can easily checkin an old
	   file on top of a new revision added by CVS, discarding work
	   committed earlier by CVS users.

	   See the howling mob scenario described above.


	RCS is great.  I have used it for years.  But I wouldn't mix it
	this way.  In a two-camp society, you are asking for real trouble,
	both in technical hassles to clean up and in political hassles to
	soothe.	 Branch merges will also be a major problem.


 4D.8	I "updated" a file my friend, "bubba", committed yesterday.
	Why doesn't the file now have a modified date of yesterday?

	CVS restores dates from the RCS files only on first "checkout".
	After that, it is more important to maintain a timestamp relative
	to the other files in the working directory.

	Example: You committed a source file at 5PM.  Bubba updated his
	copy of the file, grabbing your changes, then changed and
	committed a new revision of the file at 6PM.  At 7PM, you compile
	your file.  Then you execute "update".	If CVS sets the date to
	the one in the RCS file, the file would be given a timestamp of
	6PM and your Makefile wouldn't rebuild anything that depended on
	it.  Bad news.

	Note that the same logic applies to retrieving a revision out of
	the Repository to replace a deleted file.  If CVS changes your
	file in an existing working directory, whether it was because a
	new revision was committed by someone else or because you deleted
	your working file, the timestamp on the retrieved working file
	*must* be set to the current time.

	When you first retrieve a file, there is no reason to expect any
	particular timestamp on the file within your working area.  But
	later, when dependency checking is performed during a build, it is
	more important for the timestamps on the local files to be
	consistent with each other than than it is for working files to
	match the timestamps on the files in the Repository.
	See 4D.17 for some more about timestamps.


 4D.9	While in the middle of a large "commit", how do I run other
	commands, like "diff" or "stat" without seeing lock errors?

	Type:
		cvs -n <command>


	The '-n' option to the main cvs command turns off lock checking, a
	reasonable act for read-only commands given the promise offered by
	'-n' not to alter anything.  The "diff", "log" and "stat" commands
	provide the same information (for files that are not being
	committed) when used with and without the '-n' option.

	Warning: Ignoring locks can produce inconsistent information
	across a collection of files if you are looking at the revisions
	affected by an active commit.  Be careful when creating "patches"
	from the output of "cvs -n diff".  If you are looking only at your
	working files, tagged revisions, and BASE revisions (revisions
	whose numbers are read from your ./CVS/Entries files), you should
	get consistent results.	 Of course, if you catch a single file in
	the middle of RCS activity, you might get some strange errors.

	Note that the suggested command is "cvs -n <command>".	The
	visually similar command "cvs <command> -n" has no relation to the
	suggested usage and has an entirely different meaning for each
	command.

	"cvs -n update" also works in the middle of a commit, providing
	slightly different information from a plain "cvs update".  But, of
	course, it also avoids modifying anything.

	You could also use the RCS functions, "rlog" and "rcsdiff" to
	display some of the information by referring directly to the
	Repository files.

	You need RCS version 5 or later for the commands described above
	to work reliably.


 4D.10	Where did the ./CVS/Entries.Static file come from?  What is it for?

	Each CVS working directory contains a ./CVS/Entries file listing
	the files managed by CVS in that working directory.  Normally, if
	the "update" command finds a file in the Repository that is not in
	the ./CVS/Entries file, "update" copies the appropriate revision
	of the "new" file out of the Repository and adds the filename to
	the Entries file.  This happens for files:

	   1. Added to the Repository from another working directory.
	   2. Dragged out of the Attic when switching branches with
	      "update -A" or "update -r".
	   3. Whose names were deleted from the ./CVS/Entries file.

	If the ./CVS/Entries.Static file exists, CVS will only bring out
	revisions of files that are contained in either ./CVS/Entries or
	./CVS/Entries.Static.  If a Repository file is found in *neither*
	file, it is ignored.

	The ./CVS/Entries.Static file is created when you check out an
	individual file or a module that creates working directories that
	don't contain all files in the corresponding Repository directory.
	In those cases, without an ./CVS/Entries.Static file, a simple
	"update" would bring more files out of the Repository than the
	original "checkout" wanted.

	The ./CVS/Entries.Static file can be removed by hand.  It is
	automatically removed if you run "update -d" to create new
	directories (even if no new directories are created).
	(Internally, since "checkout" turns on the '-d' flag and calls the
	"update" routine, a "checkout" of a module or directory that
	writes into an existing directory will also remove the
	./CVS/Entries.Static file.)


 4D.11	Why did I get the wrong Repository in the loginfo message?

	You probably:

	   1. Use multiple Repositories.

	   2. Configured CVS to use absolute pathnames in the
	      ./CVS/Repository file.

	   3. Configured CVS not to use the ./CVS/Root file.

	   4. Typed the "commit" command in one Repository with your
	      $CVSROOT pointing at another.

	"commit" and all other CVS commands will heed an absolute pathname
	in the ./CVS/Repository file (or in the "-d CVSrootdir" override),
	but the log function doesn't take arguments -- it just looks at
	$CVSROOT.

	If you avoid even one of the four steps above, you won't see this
	problem.   If you configure ./CVS/Root, you won't be allowed to
	execute the program causing the error.


 4D.12	How do I run CVS setuid so I can only allow access through the
	CVS program itself?

	Setuid to root is not a great idea.  Any program that modifies
	files and is used by a widely distributed group of users is not a
	good candidate for a setuid program.  (The worst suggestion I've
	ever heard was to make *Emacs* setuid to root.)

	Root access on Unix is too powerful.  Also, it might not work in
	some (secure?) environments.

	Running it setuid to some user other than root might work, if you
	add this line to main.c near the beginning:

		setuid(geteuid());

	Otherwise it uses *your* access rights, rather than the effective
	uid's.

	Also, you have to invent a fake user whose name will show up in
	various places.	 But many sites, especially those who might want a
	setuid CVS for "security", want personal accountability -- no
	generic accounts.  I don't know whether accountability outweighs
	file security.

	And finally, unless you take action to limit the "admin"
	command, you are leaving yourself unprotected anyway.


 4D.13	How about using groups and setgid() then?

	Here is a way to run CVS setgid in some environments:

	0. Stick this near the front of the main() in main.c:

		setgid(getegid());

	   This will allow "access" to work on systems where it
	   only works on the real gid.

	1. Create a group named "cvsg". (This example uses "cvsg".  You
	   can name it as you wish.)

	2. Put *no* users in the "cvsg" group.	You can put Repository
	   administrators in this group if you want to.

	3. Set the cvs executable to setgid (not setuid):

		cd /usr/local/bin; chown root.cvsg cvs; chmod 2755 cvs

	4. Make sure every file in the Repository is in group "cvsg":

		chown -R root.cvsg $CVSROOT

	5. Change all directory permissions to 770.  This allows all
	   access to the files by the "cvsg" group (which has no members!)
	   and no access at all to anyone else.

	      find $CVSROOT -type d -exec chmod 2770 {} \;

	   On some systems you might have to type:

	      find $CVSROOT -type d -exec chmod u=rwx,g=rwx,o=,g+s {} \;

	This should allow only the cvs program (or other "setgid to group
	cvsg") programs to write into the area, but no one else.  Yes the
	user winds up owning the file, but s/he can't find it again later
	since s/he can't traverse the tree.  (If you enable the world
	execute bit (mode 2771) on directories, users can traverse the
	tree and the user who last wrote the file can still write to it.)

	If you want to allow read access, check out an entire tree
	somewhere.  You have to do this anyway to build it.

	Note: If you are using a stupid file system that can't inherit
	file groups from the parent directory (even with the "setgid"
	(Octal 2000) bit set), you might have to modify CVS (or RCS) to
	reset the group every time you create a new file.  I have not
	tested this.

	The setgid() method shares with the setuid() method the problem of
	keeping "admin" from breaking things.


 4D.14	How do I use the "commitinfo" file?

	Go read 4B.2 first.

	The "commitinfo" file allows you to execute "sanity check"
	functions before allowing a commit.  If any function called from
	within the commitinfo file exits with a non-zero status, the
	commit is denied.

	To fill out a "commitinfo" file, ask yourself (and those sharing
	your Repository) these questions:

	- Is there anything you want to check or change before someone is
	  allowed to commit a file?  If not, forget commitinfo.

	  If you want to serialize  binary files, you might consider
	  something like the rcslock.pl program in the contrib directory
	  of the CVS sources.

	- Do you want to execute the same exact thing before committing to
	  every file in the Repository?	 (This is useful if you want to
	  program the restrictions yourself.)  If so, set up a single line
	  in the commitinfo:

		DEFAULT		/absolute/path/to/program

	  CVS executes the program once for each directory that "commit"
	  traverses, passing as arguments the directory and the files to
	  be committed within that directory.

	  Write your program accordingly.  Some examples exist in the
	  contrib directory.

	- Do you want a different kind of sanity check performed for
	  different directories?  If so, you'll have to decide what to do
	  for all directories and enter lines like this:

		regexp1		/absolute/path/to/program-for-regexp1
		regexp2		/absolute/path/to/program-for-regexp2
		DEFAULT		/absolute/path/to/program-for-all-else


	- Is there anything you want to happen before *all* commits, in
	  addition to other pattern matches?  If so, include a line like
	  this:

		ALL		/absolute/path/to/program

	  It is executed independently of all the above.  And it's
	  repeatable -- you can have as many ALL lines as you like.


 4D.15	How do I use the "loginfo" files?

	See 4B.2 and the "commitinfo" question above.

	The "loginfo" file has the same format as the "commitinfo"
	file, but its function is different.  Where the "commitinfo"
	information is used before a commit, the "loginfo" file is used
	after a commit.

	All the commands in the "loginfo" file should read data from
	standard input, then either append it to a file or send a message
	to a mailing list.  If you want to make it simple, you can put
	shell (the shell used by "popen(3)") command lines directly in the
	"loginfo" (or "commitinfo") file.  These seem to work:

	    ^special  /usr/ucb/Mail -s %s special-mailing-list
	    ^other    /usr/ucb/Mail -s %s other-mailing-list
	    DEFAULT   (echo '===='; echo %s; cat) > /path/name/to/log/file


 4D.16	How can I keep people with restrictive umask values from blocking
	access to the Repository?

	If a user creates a new file with restricted permissions
	(e.g. 0600), and commits it, the Repository will have a file in it
	that is unreadable by everyone.	 The 0600 example would be
	unreadable by *anyone* but root and the user who created it.

	There are 3 solutions to this:

	0. Let it happen.  This is a valid way to protect things.  If
	   everyone is working alone, a umask of 077 is OK.  If everyone
	   is working only in small groups, a umask of 007 is OK.

	1. Train your users not to create such things if you expect to
	   share them.

	2. See 4B.5 for a small script that will reset the umask.

	   I personally don't like the idea of a program automatically
	   *loosening* security.  It would be better for you all to talk
	   about the issue and decide how to work together.


 4D.17	Why do timestamps sometimes get set to the date of the revision,
	sometimes not?	The inconsistency causes unnecessary recompiles.

	The "checkout" command normally sets the timestamp of a working
	file to match the timestamp stored on the revision in the
	Repository's RCS file.

	The "commit" command retains the timestamp of the file, if the
	act of checking it in didn't change it (by expanding keywords).

	The "update" command sets the time to the revision time the first
	time it sees the file.	After that, it sets the time of the file
	to the current time.  See 4D.8 for a reason why.

	Here's a two-line PERL program to set timestamps on files based on
	other timestamps.  I've found this program useful.  When you are
	certain you don't want a source file to be recompiled, you can set
	its timestamp to the stamp on the object file.

	#!/usr/local/bin/perl
	#
	# Set timestamp of args 2nd-Last to that of the first arg.
	#
	($dev,$ino,$mode,$nlink,$uid,$gid,$rdev,$size,$atime,$mtime,$ctime)
		= stat(shift);
	utime($atime,$mtime,@ARGV);



----------------
-- Section 4E --	Internal errors
----------------

 **** Questions:

 4E.1	Explain: "ci error: unexpected EOF in diff output"
 4E.2	Explain: "RCS file /Repository/module/file.c,v is in use"
 4E.3	Explain: "co error, line 2: Missing access list"
 4E.4	Explain: "error: RCS file name `xyz .c' contains white space"
 4E.5	Explain: cvs checkout: warning: <X> is not (any longer) pertinent
 4E.6	Why did a Repository file change from <file>,v to ,<file>,?


 **** Answers:

 4E.1	Explain: "ci error: unexpected EOF in diff output"

	RCS versions earlier than 5.5 print the above error when a file
	does not end in a newline character.  It can be caused by:

	  - Editing with Emacs and not using "require-final-newline".
	  - Committing a binary file.
	  - Filesystem failures (NFS!) that put nulls in your file.

	The solution is to upgrade to RCS 5.5 or later.	 (Of course, this
	won't fix filesystem failures.	It will merely allow RCS (and
	therefore CVS) to handle the file without error.)


 4E.2	Explain: "RCS file /Repository/module/file.c,v is in use"

	This is an RCS error that occurs when its internal lock file has
	been left around by an RCS command interrupted by some sort of
	system crash, disk failure or SIGKILL signal.

	Go into the Repository and look for files with names similar to
	"file.c,v", usually starting with ',', '_' or '#'.  Make
	sure they are really crash remnants and do not belong to
	transactions in progress -- a recent last-modified timestamp
	is a good indicator of a live transaction.  Delete them if they
	are old.


 4E.3	Explain: "co error, line 2: Missing access list"

	This is an error message from RCS Version 3 when it tries to read
	a file created by a later version of RCS.

	HP decided to "standardize" on an ancient version of RCS some time
	ago.  You can't use it for CVS.	 See 4H.6.

	Since the error comes from having a later version of RCS than HP
	supports, you probably did install the later version but must have
	recently changed your $PATH or installed the HP package that has
	RCS in it.

	You should either reconfigure CVS to use absolute pathnames to the
	proper versions of the RCS programs that CVS uses, or change your
	PATH to look there first.  If you haven't installed the latest
	version of RCS, you should upgrade.  See 1B.4


 4E.4	Explain: "error: RCS file name `xyz .c' contains white space"

	RCS 5.6 doesn't allow white space in filenames.	 Apparently this
	restriction will be removed in RCS 5.7, but CVS may still require
	that filenames have no white space in them.


 4E.5	Explain: cvs checkout: warning: <X> is not (any longer) pertinent

	This message occurs in three instances:

	1. When there is an entry in the ./CVS/Entries for file <X> and
	   there is no RCS file in the Repository to back it up.

	   If the working file exists, and hasn't changed (determined from
	   the timestamp) it is removed.


	2. When you try to check out a piece of the Repository with:

		cvs checkout some/place/in/repository/tree

	   and at least the first element of the path (i.e. "some" in the
	   above) exists, but some part of the rest of it does not.

	   The checkout command checks the modules file first for the
	   whole path, then for a prefix of the path as a module name.	If
	   it doesn't find *any* portion of your path in the modules file,
	   it says:

		cvs checkout: cannot find module `<module/path>' - ignored

	   If it finds some set of prefix directories, it prints the
	   message you see.

	   In practice this is usually a spelling error.

	3. If the Repository files you are trying to check out or update
	   are not readable by you, the same problems can occur.
	   Check the permissions on the files involved.



 4E.6	Why did a Repository file change from <file>,v to ,<file>,?

	This is an RCS problem, since the ,<file>, syntax for file names
	is used by RCS and not CVS.

	RCS constructs a new <file>,v in a temporary file named ,<file>,
	(which doubles as a lock file) then renames it to <file>,v when it
	is done.  The only way this is reliable is if your system's
	version of rename(2) is an atomic, as required by POSIX.

	If your system has a non-atomic (and therefore non-POSIX)
	rename(2) system call, RCS runs uses an internal version of this
	algorithm to approximate the atomic rename:

	   rm <file>,v; ln ,<file>, <file>,v; rm ,<file>,

	If the system crashes, or you lose your NFS connection between the
	first "rm", but before the "ln", you can be left only with the
	,<file>, file.	If the crash or network failure occurs between the
	"ln" and the final "rm", you could be left with a pair of linked
	names.

	Recovery:
	- If only the ,<file>, exists, rename it to <file>,v.

	- If both ,<file>, and <file>,v exist and are linked, remove the
	  ,<file>, file.

	- If both ,<file>, and <file>,v exist and are separate files, look
	  at the dates, "diff" them and make your best guess.  This sounds
	  like the remnants of two separate events.



----------------
-- Section 4F --	Related Software
----------------

 **** Questions:

 4F.1	How do I use CVS under Emacs?  Is there an Emacs cvs-mode?
 4F.2	What is GIC (Graphical Interface to CVS)?
 4F.3	What is CAVEMAN?


 **** Answers:

This section covers a small handful of subsystems that connect to CVS in
some way.  Most are "front ends" in that they offer a different user
interface to CVS, but use CVS to perform the normal tasks.

 NOTE:	The short summaries below combine details culled from public
	announcements of the listed software with the personal opinions of
	the author of the FAQ entry.

 4F.1	How do I use CVS under Emacs?  Is there an Emacs cvs-mode?

	The pcl-cvs package distributed with CVS is an emacs package that
	helps with the update/commit process.  When you are ready to
	update, you use the 'cvs-update' command within emacs.	This
	executes "update" and fills a cvs-mode buffer with a line for each
	file that changed.  The most helpful features are: descriptive
	words for what happened (i.e. Merged or Conflict rather than 'U'
	or 'C'), single keys bound to diffs and commits, and the ability
	to mark arbitrary groups of files, possibly from different
	directories, for commit as a whole.

	All the developers in my group that use emacs find pcl-cvs a much
	friendlier and more helpful way to update/commit than raw cvs.
	One vi user even converted to emacs just to use pcl-cvs.

				Contributed by Jeffrey M Loomis

 4F.2	What is GIC (Graphical Interface to CVS)?

	GIC provides a graphical user interface to the Concurrent Version
	System (CVS), a powerful revision control system.  GIC is
	implemented in the Tcl/Tk programming language and is intended to
	augment the sometimes cumbersome CVS command line interface.
	Novices should find GIC to be much easier to learn than the CVS
	command line.

	While GIC is easy to use, it does not contain any documentation on
	CVS.  Users of GIC must first learn the concepts of CVS such as
	modules and merging, as well as the simple functions, such as
	committing and updating.  The CVS manual page and the README file
	are good places to look.

	contact
		David Marwood
		marwood@cpsc.ucalgary.ca

			[Extracted from an announcement by David Marwood.]

	GIC can be obtained by anonymous ftp to (on the date of this FAQ)

		ftp.cpsc.ucalgary.ca:/pub/users/marwood/gic-1.1.tar.Z
		ftp.cpsc.ucalgary.ca:/pub/users/marwood/gic-1.2b1.tar.Z


 4F.3	What is CAVEMAN?

	CAVEMAN is a front end to CVS written in PERL providing a
	collection of features desired by the site where it was developed.

	- The ability to spread a "project" over multiple Repositories.
	- Optional automatic tagging after each commit.
	- Additional locking of files.
	- Extra before and after program hooks.
	- A layer of event logging.
	- All sorts of error messages.
	- Many changes to the semantics of commands.

	It is available via anonymous ftp on ftp.llnl.gov [128.115.54.18]
	in gnu/caveman_vX.Y.Z.tar.gz  (The numbers X, Y, & Z vary.)

	contact
	Kathleen Dyer		kdyer@llnl.gov
				(510)423-6803
				(510)423-5112 FAX

	[[Does someone want to elaborate?]]


----------------
-- Section 4G --	Engineering
----------------

 **** Questions:

 4G.1	Where can I find out about Software Engineering?
 4G.2	How do I flexibly arrange the modules file to describe my sources?
 4G.3	Can I have multiple source repositories, one for each project?
 4G.4	Who should administer the Repository and manage the modules file?
 4G.5	Isn't disk space a big factor?	CVS copies files out of the
	Repository, duplicating everything.


 **** Answers:

This section is really beyond the scope of CVS, but so many people ask
questions about how to do Software Configuration and Engineering that I
thought I'd try to include some information.  If you have any
improvements, references or ideas, speak up.



 4G.1	Where can I find out about Software Engineering?

	A couple different people suggested this book:

	Software Configuration Management:  Coordination for Team
	Productivity; Wayne A. Babich; Addison Wesley; 1986;
	ISBN 0-201-10161-0


	A number of others suggested Appendix B of the book "Decline and
	Fall of the American Programmer" by Ed Yourdon, called "The
	Programmer's Bookshelf".  It list 87 books you are expected to
	have read.  Since they publish many of the books, Prentice-Hall
	distributes this list as "Prentice Hall Professional Technical
	reference PTR-125-AA3.

	One interesting item from the Yourdon book:  The total number
	of professional computer books sold is less than the number
	of programmers currently in the United States.	It wasn't clear
	from the book whether this meant "per year" or not, but it is
	still frightening.


 4G.2	How do I flexibly arrange the modules file to describe my sources?

	An equivalent question might be, "How do I structure my sources?"
	This can be a difficult question especially in the areas that are
	more political than technical.

	Generally you want to think about which pieces of your system need
	to be checked out together, built as one system or tagged as a
	consistent whole.  You should certainly create module names that
	correspond to complete, buildable collections that you would tag
	and release as one "product".  It is also convenient to create
	module names for small sections of the Repository containing
	files that will all be worked on at the same time by the same
	person or group.

	Once you have defined the structure of your work, you can usually
	see how to lay it out in a Repository.	After that the modules
	file is easy.  You set up module names and aliases to match what
	you need to check out by name.	If you like relative directories,
	it is possible, but not recommended, to work completely without a
	modules file.  See 1D.11 and 2C.7 for some info about the modules
	file.

	Here are a few types of modules.  You should experiment to see
	what kind of structure each of these produces.	They all have
	different uses.

	1. Connected projects in one group with two separate helper
	   directories.	 The helper directories can contain build tools,
	   header files, libraries, or whatever you like.

	   These are all aliases that checkout relative pathnames.  The
	   equivalent results could be produced by placing the selected
	   relative pathnames on the "cvs checkout" command line.

	   pr1	-a P1 HELPERS
	   pr2	-a P2 HELPERS
	   pr3	-a P3 HELPERS
	   pr12 -a P1 P2 HELPERS
	   pr13 -a P1 P3 HELPERS
	   pr23 -a P2 P3 HELPERS

	   P1		-a group1/proj1
	   P2		-a group1/proj2
	   P3		-a group1/proj3
	   HELPERS	-a group1/helper1 group1/helper2 MAKEFILE
	   MAKEFILE	-a group1/Makefile

	   Actual Repository directory structure: (from $CVSROOT down)

	   group1/
		Makefile
			The top level Makefile.
		helper1/
		helper2/
			Helper files and dirs
		proj1/
			Files and dirs
		proj2/
			Files and dirs
		proj3/
			Files and dirs

	   "checkout group1" produces a duplicate of the above.
	   "checkout projX" produces all but "projY" and "projZ".
	   "checkout projXY" produces all but "projZ".


	2. Here is the exact same set of module names describing the same
	   Repository layout using module names (and aliases containing
	   module names) instead of merely aliases for relative pathnames.

	   There is one difference in the result.  The name of the top
	   level directory in the checked out working tree will match the
	   "module" name (e.g. pr1) instead of always being "group1" as it
	   was in the first example above.

	   pr1	group1 proj1 &HELPERS
	   pr2	group1 proj2 &HELPERS
	   pr3	group1 proj3 &HELPERS
	   pr12 group1 proj1 proj2 &HELPERS
	   pr13 group1 proj1 proj3 &HELPERS
	   pr23 group1 proj2 proj3 &HELPERS

	   HELPERS	-a helper1 helper2 group1-Makefile
	   helper1	group1/helper1
	   helper2	group1/helper2
	   group1-Makefile -d . group1 Makefile

		The above line (with the -d in it) says that when the
		module named "group1-Makefile" is checked out, the file
		named Makefile file will be found in a directory named
		$CVSROOT/group1 and will be checked out into a directory
		named '.', which obviously already exists.

		The & references say to interpret those pathnames relative
		to the directory where the whole module is stored.  For
		the "pr1" module, that directory is "group1", so the
		&HELPERS reference winds up placing Makefile in '.'
		relative to "group1".


	3. A short one containing the basic "module" actions:

	   m1		head/path file1 dir2 file3 dir4 file5

		When checked out, a directory named "m1" appears in your
		current directory.  Elements named file1, dir2, file3,
		dir4, and file5 appear in it.  They were originally taken
		as relative paths from $CVSROOT/head/path.


	4. Here's another way to construct a working directory out of
	   pieces of the Repository:

		projX	projX Makefile &projX_inc &projX_src &projX_doc

		# The first line selects a single file within projX, plus
		# the contents of three other modules.	Those three other
		# modules rename their directories.

		projX_inc -d include projX/inc
		projX_src -d source projX/src
		projX_doc -d documentation projX/doc


	5. A Unix tree.	 This is similar to what CVS was developed for and
	   the way I have used it for years.

		# Top level
		unix		unix
		u_bin		unix/bin
		u_etc		unix/etc
		u_man		unix/man
		usr-bin		unix/usr.bin

		# Subdirs of top level dirs.  (tiny subset)
		ls		unix/bin/ls
		fsck		unix/etc/fsck
		man8		unix/man/man8

		# Programs without subdirs. (tiny subset)
		cat		unix/bin Makefile cat.c
		uniq		unix/usr.bin Makefile uniq.c

		# /usr/local/src
		localsrc	localsrc
		gnu		localsrc/gnu
		public		localsrc/public
		X11		localsrc/X11

		# GNU and PD tools
		cvs		localsrc/gnu/cvs
		emacs		localsrc/gnu/emacs
		rcs		localsrc/gnu/rcs
		btoa		localsrc/public/btoa
		tcsh		localsrc/public/tcsh

		# X11 related items.
		tvtwm		localsrc/X11/contrib/tvtwm

	   "unix" was checked out and built from the top down, using a set
	   of Makefiles that knew about the whole structure.  "localsrc"
	   was kept checked out in /usr/local/src.

	   At any time I could run "checkout ls" or "checkout cat" and get
	   a simple directory with only that tool in it, plus a subset
	   Makefile that knew how to build that tool against the installed
	   (or alternate, via environment variables) headers and libraries.

	   I found it very handy to be able to run "ls" and see the three
	   tools I was porting that week.


 4G.3	Can I have multiple source repositories, one for each project?

	Yes, you can have as many Repositories as you like.  But each
	Repository must be managed separately, creating additional work.

	Question 4A.1 provides a short description of setting up a
	single Repository.  A few additional considerations:

	1. It is a good idea to start by creating a single Repository and
	   split it up (or create additional Repositories) only if you
	   believe it is really necessary.  I would only create a new
	   Repository if the data is completely disconnected from the rest
	   of the main Repository.

	2. If there is a lot of overlap among the developers working on
	   the collections of files you want to place in different
	   Repositories, or if there is any connection between those
	   collections, I would go out of my way to create a single
	   Repository.	It is much easier to manage.

	3. Disk space should not be a factor since you can build up a
	   Repository using symbolic links and/or remote mounts.

	4. Each Repository is completely distinct.  You can't check out
	   modules from different Repositories at the same time.  A better
	   way of looking at it is that if you *can* check out two modules
	   or directories with a single "checkout" command (without
	   contortions or explicit absolute pathnames), then they are in
	   the same Repository.

	5. To "checkout" modules from multiple Repositories, you must use
	   the "cvs -d" option on all CVS commands or alter your $CVSROOT
	   variable when you change focus to another Repository.  If you
	   work with multiple Repositories, it is a good idea to configure
	   CVS to use absolute pathnames in the ./CVS/Repository file,
	   since most commands (other than "checkout") will use that file
	   rather than $CVSROOT.

	6. If you configure CVS to use relative pathnames in your
	   ./CVS/Repository files, you must always be careful to set your
	   $CVSROOT properly or you will get unexpected results.

	   If you have two modules or directories by the same name at the
	   same relative path inside two different Repositories, you are
	   asking for disaster.	 You could unexpectedly update a directory
	   with completely unrelated files.  This is not a fanciful
	   example -- a Repository is occasionally duplicated for release
	   purposes in which case *all* the paths in the two Repositories
	   are the same.


 4G.4	Who should administer the Repository and manage the modules file?

	This is a "management style" question.	In large or traditional
	groups, the CVS procedures are warped to conform to local
	conventions.  In small groups, in groups with strong personalities
	or on new projects the choice of source control procedures can
	help create some of the working environment.  Here is a taxonomy
	of environments I have worked in or helped set up:

	Situation 1.

	    A small number of competent developers working on a medium
	    size project.  We all got along and we all respected each
	    other (at least technically).  Anyone edited anything.

	    Modules and Repository admin was mostly left to me.	 I never
	    found a problem in minor changes made by anyone else.


	Situation 2.

	    A large number of experienced developers sprinkled with
	    wackos.  Many of the developers didn't want to deal with any
	    kind of source control.  They wanted a full-service source
	    control system that caused them zero thought.

	    I learned "big stick" diplomacy here.  There was a small
	    number of "designated" (by me) people who were allowed to do
	    *anything* other than "update" and "commit".  Even "checkouts"
	    were controlled.  This is where I found "history" and
	    "release" the most useful.

	Situation 3.

	    A small number of developers who wanted me to "help", but who
	    didn't want to deal with anything other than their favorite
	    algorithms.

	    I didn't have the time to baby-sit this group, so I designated
	    one of them to be my official contact and made him do it all.
	    He felt sullied by the requirement to pay attention to
	    anything other than his pet coding projects, but enjoyed the
	    "status" of being the only one who could touch the control
	    files without my kicking the chair out from under him.

	Situation 4.

	    A huge number of developers of covering the whole spectrum of
	    competence and experience split into 20 groups, none of which
	    cooperated with the others, working on 57 different projects,
	    most of which didn't inter-operate.

	    Managing it in any coherent way was not my responsibility (and
	    beyond my tolerance for chaos).  Too many people.  So I
	    privately designated a person in each group to be the contact
	    and kept watch on the Repository activity.	When something
	    went wrong, I notified the contact for the group and told him
	    what was happening and *he* kept his troops in line.  They
	    were tougher with their own group that I would have been.

	    Eventually only a few people were willing to touch the control
	    files, since they were flamed from all directions if they
	    screwed up.

	Situation 5.

	    In a medium group of really *serious*, and seriously
	    overworked, people, someone else was designated the "master".
	    I convinced the master I knew what I was doing and went on my
	    way.

	    No one else in the world was allowed to touch anything.

	Situation 6.

	    In a large amorphous group of beginners, experts and clowns,
	    over whom no one had official control, I was forced to employ
	    a group of relative beginners (who became experts rather
	    quickly) to police the world.  The ultimate in locking the
	    barn after the horse was stolen, we kept Chaos from destroying
	    us only by use of superior firepower.



	My choice, if allowed, is to let anyone touch anything.	 I keep
	backups of important items and let people know individually
	whether I want them to touch things or not.  If someone on my "no
	touch" list touches and succeeds, they are allowed more slack.	If
	they screw up after being warned, their screwup becomes public.
	After a few months, I usually have no trouble keeping the world
	running smoothly, at least from my (and CVS's) perspective.


 4G.5	Isn't disk space a big factor?	CVS copies files out of the
	Repository, duplicating everything.

	Everyone knows that disk space is getting cheaper.  How do we
	reconcile this with the equally well-known problem that *all* disk
	is *always* filled up?

	In my opinion, the main reason disk space will never be an
	unlimited resource is that it is the major variable in
	organizational time/space tradeoffs.  It isn't a problem of waste
	or an aspect of Murphy's law, as some claim it is, but rather a
	direct consequence of good management.	Disk space is, and will
	always be, a limited resource.

	First, the cost of *deploying* that disk is not dropping as fast
	as the cost of the storage medium.  The cost of machines to hold
	the disks and the networks to connect them are dropping more
	slowly than disk media.	 And the cost of the human time necessary
	to manage the machines, networks, disks, and the developers using
	them, is not dropping at all.  The cost of human time continues to
	rise.

	If management decides that expensive human time can be saved by
	using all that new disk space to keep the last three releases
	online, then that's what it will be used for.  If each release
	takes up a Gigabyte and you support 30 platforms, a simple
	time-saving suggestion has just grabbed 100 Gigabytes of disk
	space.	And we've ignored the potential disk storage needed to
	support "better Customer Service", another management refrain.

	Even at 30 cents per Megabyte (next year's price), you've just
	used up $30,000 of disk space. And that doesn't count the
	computers, tape drives and humans necessary to maintain and deploy
	all of it.  Spending money to save time has its own overhead, too.


	Binaries are getting bigger.  Graphics and data collection devices
	can eat up any amount of disk.	There are more tools available,
	more libraries, more raw data than you can ever store.	My home
	computer has a Gigabyte of disk on it.	It could easily handle 30.

	The "economy" of disk storage media will never remove the need to
	manage disk space.


	So, here's an un-reviewed suggestion originally from Graydon Dodson
	<grdodson@lexmark.com>, which I've altered and edited heavily.

	- Keep a directory where the whole tree is checked out.	 (It might
	  be built and tested once in a while to make sure it is worth
	  linking to, but that doesn't affect the source control aspect of
	  this procedure).  Let's call it /master/build.

	- Write a tool that creates a tree of directories (like the X11
	  "lndir" command) filled with links to the checked out files in
	  the /master/build tree.

	  This tool should also provide real copies of, not symlinks to,
	  all the files within the CVS administrative directories.

	- You could also provide a way for the tool to take a list of
	  whole directories that you will never change, for which it would
	  create a single symlink to the directory and not a subtree of
	  symlinks to files.  Or you could rm -r pieces of the resulting
	  working directory yourself and replace it with links.

	- If you want to edit a file, you have to grab a real copy and
	  keep it until your revision shows up in the /master/build tree.
	  I'd create a script to do this:  cvsgrab <file>

		#!/bin/csh -f
		set f = $1
		if (! -l $f) then
		   echo "file $f is not a symlink"
		   exit 1
		endif
		rm $f
		set rev = `grep "^/$f/" CVS/Entries | awk -F/ '{print $3}'`
		cvs update -p -r $rev $f > $f

	  You can't do a plain "cvs update" since that would grab newer
	  revisions from the Repository, not the revision you wanted to
	  start with.  After the file is no longer a symlink, you can work
	  normally.  You'll have to run "update" before "commit" anyway if
	  there are newer revisions.

	- Presumably there would also be a tool to traverse the link tree
	  and revert it to links if there are no modified files and/or if
	  all the real files match the revision of the /master/build tree.

	- To avoid confusing CVS when the /master/build revisions are
	  updated but your CVS/Entries files is not, CVS would have to
	  change to handle symlinks.  It currently causes problems with
	  this scenario:

		1. ./<file> is a symlink.
		2. ./CVS/Entries says you are revision 1.2.
		3. The corresponding CVS/Entries file in /master/build
		   says the latest revision is 1.3.
		4. cvs update <file> shows a 'C' conflict flag.


----------------
-- Section 4H --	Other Systems
----------------

 **** Questions:

 4H.1	I use a NeXT.  Is there anything I need to know?
 4H.2	I use OS/2 and/or DOS.	Is there anything I need to know?
 4H.3	I use SCO Unix.	 Is there anything I need to know?
 4H.4	I use AIX.  Is there anything I need to know?
 4H.5	I use IRIX.  Is there anything I need to know?
 4H.6	I use an HP system.  Is there anything I need to know?
 4H.7	I use AFS.  Is there anything I need to know?
 4H.8	I use A/UX.  Is there anything I need to know?


 **** Answers:

Out of the box, CVS works on most varieties of Unix.  Some near-Unix
systems have a few problems and non-Unix systems have a *lot* of problems.

 4H.1	I use a NeXT.  Is there anything I need to know?

	NeXTSTEP 3.0's Interface Builder uses "nib" directories, rather
	than the files used in previous revisions.  It removes files it
	doesn't recognize, making it impossible to place such a directory
	under CVS -- the CVS admin directory will be removed.

	Some time ago, <Bob_Vadnais@pdh.com> posted a palette named
	CVSPalette that claimed to resolve this problem.  It was intended
	to preserve the CVS administrative directories within nib
	documents (directories) that Interface Builder usually removes.

	CVSPalette is no longer in its announced place:

		ftp.cs.orst.edu:/pub/next/submissions

	though I did find two other interesting files on ftp.cs.orst.edu:

		/software/NeXT/sources/tools/cvs-next-2_1_1.tar.Z

	which is a port of CVS 1.3 (along with RCS and diff) and:

		/software/NeXT/sources/programming/cvs.postamble-2.4.gz

	which appears to be a set of wrappers for CVS commands that claim
	to allow you to use CVS effectively (and without need for the
	"command line") on a NeXT machine.


	[[Anyone know the truth about CVS and NeXT?]]


 4H.2	I use OS/2 and/or DOS.	Is there anything I need to know?

	You can share RCS files between Unix and DOS while avoiding the
	MS-DOS file name limits by setting your RCSINIT environment
	variable to '-x/,v'.  New RCS files will be created without the
	standard ",v" suffix, though files ending in ",v" will still be
	found if there is no matching file in the same directory without
	the ",v".

	Erik van Linstee <linstee@dutecaj.et.tudelft.nl> offers an
	OS/2 and a DOS port of CVS 1.3 in:

	   ftp.informatik.tu-muenchen.de:/pub/comp/os/os2/gnu/devtools
	or
	   ftp.rrzn.uni-hannover.de:/pub/os2-local

	The files are named:

		cvs13p?[bs].zip

	Where the ? stands for the patch level (currently 8) and the b is
	for the binaries, the s for the sources.

	There are three binaries. An OS/2 only one (32-bit), a DOS only one
	(16-bit) and an EMX one that runs on both (32-bit).

	There are many differences between the Unix and the DOS versions
	of CVS.	 Read the material that comes with the DOS version before
	using it.

	[[Updates?]].


 4H.3	I use SCO Unix.	 Is there anything I need to know?

	On SCO/UNIX 3.2 V2.0 POSIX signals don't work. Unfortunately the
	configure program detects POSIXness and configures in the use of
	POSIX signals. Workaround : Edit out the check for POSIXness in
	the configure script. [[You could also remove all occurrences of
	"-DPOSIX=1" from the Makefiles after configure is run.	-dgg-]]

	SCO/UNIX doesn't understand #!/<some shell> syntax. This breaks
	the use of log.pl as it gets invoked by /bin/sh instead of
	!#/usr/local/bin/perl. WorkAround : edit log.pl and change it into
	a shell script which invokes perl with log.perl (renamed from
	log.pl) as input.
				Contributed by Joe Drumgoole


 4H.4	I use AIX.  Is there anything I need to know?

	The only report on AIX claims to have no trouble using it in
	concert with SunOS and IRIX platforms.


 4H.5	I use IRIX.  Is there anything I need to know?

	If you see "uid" numbers where you would expect user names, try
	adding -lsun to the link line.	Without it CVS is unable to
	retrieve "passwd" data through NIS.


 4H.6	I use an HP system.  Is there anything I need to know?

	HP distributes RCS version 3 (a circa 1983 release!) with HP-UX.
	CVS does not work with RCS version 3; it requires RCS version 4
	or later.  Your best bet is to find the latest version of RCS
	and install it somewhere.

	HP-UX 8.07 has a serious bug with the mmap system call and NFS
	files; the bug can crash the operating system.	Make sure that
	you configure RCS to avoid mmap by setting has_mmap to 0 in
	RCS's conf.h.  This bug is fixed in HP-UX 9.

				Contributed by Paul Eggert

	If using the setgid() trick described in 4D.13, you will have to
	create an entry in the /etc/privgroup file to give the group
	assigned to the cvs executable setgid permission (see
	setprivgrp(1m)).  Additionally, if you are restricting "read"
	access to the Repository by limiting access to the executable
	(this requires yet another group), then you will require that
	/etc/logingroup exists and is configured correctly (usually it's
	just alink to /etc/group).

				Contributed by Dale Woolridge


 4H.7	I use AFS.  Is there anything I need to know?

	There is a problem with the way CVS performs its locking when the
	files are within AFS. When your current PTS id != your uid, the
	locks are not deleted.	The stat() system call returns the PTS id
	of the owner. If that id != your uid, CVS assumes you did not lock
	it, and leaves the lock files alone.  The next time you try to use
	it, it complains that someone has the repository locked.

				Contributed by Michael Ganzberger

	[[This was against CVS 1.3.  Is it still in CVS 1.4?]]


 4H.8	I use A/UX.  Is there anything I need to know?

	[[??]]




=============================================
==  Section 5	====	Past & Future	 ====
=============================================

----------------
-- Section 5A --	Contributors
----------------

 **** Questions:

=5A.1	Who wrote CVS?
 5A.2	You didn't write all of this FAQ, did you?


 **** Answers:


=5A.1	Who wrote CVS?

	Brian Berliner <berliner@sun.com> converted a collection of
	scripts written by Dick Grune <dick@cs.vu.nl> into a C program,
	then added all sorts of features.  He continues to maintain CVS.

	Jeff Polk <polk@bsdi.com> wrote much of the code added between
	revisions 1.2 and 1.3.	Many others were involved at some level.

	david d zuhn <zoo@armadillo.com> fixed a number of bugs, added
	some of the new features, reworked the whole thing to be more
	portable, and provided much of the energy to push CVS 1.4 out
	the door.

	Jim Kingdon implemented CVS 1.5's remote repository access
	features, fixed many bugs, and managed the release of version 1.5.

	Take a look at the README and the ChangeLog files in the CVS
	sources for more contributors.


 5A.2	You didn't write all of this FAQ, did you?

	In the original hunt for questions to answer (performed in
	Jan/Feb, 1993), I polled hundreds of people and I rephrased all
	sorts of text found on the net.	 Between 2/93 and 10/93, I
	released about 20 versions, with corrections and additions from
	the info-cvs mailing list and private correspondence.

	Between 10/93 and 10/94 I extracted frequently asked questions
	from the 1200 mail messages to the info-cvs mailing list,
	turned them into focused questions and tried to answer them.

	93/02/??	~4000 lines
	93/06/??	~5000 lines
	93/10/23	 7839 lines	278K
	94/10/29	 9856 lines	360K
	95/05/09	 9981 lines	365K

	Because there are so many posers of questions, I will list only
	those who contribute answers or help significantly with the
	content and structure of this document.

	If I used someone else's text verbatim, I mentioned it in the
	given answer.  The people whose email postings have added to this
	document or who have added to my understanding are:

	Brian Berliner <berliner@sun.com>, CVS maintainer.
	Paul Eggert <eggert@twinsun.com>, RCS maintainer.

	Gray Watson <gray@antaire.com>
	Per Cederqvist <ceder@signum.se>
	Pete Clark <pclark@is.com>

	    all of whom have sent me copies of their tutorials
	    and local CVS documentation.

	Additional contributors, who have sent me ideas, text, corrections
	and support include (in alphabetical order):

	Per Abrahamsen		<amanda@iesd.auc.dk>
	Donald Amby		<amby@mixcom.mixcom.com>
	Mark D Baushke		<mdb@cisco.com>
	Jim Blandy		<jimb@cyclic.com>
	Tom Cunningham		<tomc@bouwsma,sps.mot.com>
	Graydon Dodson		<grdodson@lexmark.com>
	Joe Drumgoole		<joed@splatter.demon.co.uk>
	Don Dwiggins		<dwig@markv.com>
	Bryant Eastham		<bryant@ced.utah.edu>
	Dan Franklin		<dan@diamond.bbn.com>
	Michael Ganzberger	<ganzbergermd@ES.net>
	Steve Harris		<vsh%etnibsd@uunet.uu.net>
	Erik van Linstee	<linstee@dutecaj.et.tudelft.nl>
	Jeffrey M Loomis	<jml@world.std.com>
	Barry Margolin		<barmar@near.net>
	Mark K. Mellis		<mkm@ncd.com>
	Chris Moore		<Chris.Moore@src.bae.co.uk>
	Gary Oberbrunner	<garyo@avs.com>
	Steve Turner		<stevet@carrier.sps.mot.com>
	Dave Wolfe		<dwolfe@pffft.sps.mot.com>
	Dale Woolridge		<dwoolridge@cid.aes.doe.ca>



	Please send corrections.  If I forgot you, remind me and I'll add
	your name to the list.


----------------
-- Section 5B --	Bugs and Patches
----------------

This section addresses some known bugs and patches for them.
Large patches will be stored in the FTP area.
See the Development section later for stuff being worked on.

 **** Questions:

 5B.1	Why can't CVS handle deletion of directories?
 5B.2	Why can't CVS handle the moving of sources from one place in the
	directory hierarchy to another?
 5B.3	When I typed "cvs update -D <date>", why did it check out all
	sorts of ancient files from the Attic?	Shouldn't it just create
	the set of files and revisions that existed at that date?
 5B.4	When I typed "cvs update -D <date>" in my branch, why did it
	screw up all my files?
 5B.5	When I executed "checkout" into an existing directory I got "No
	such file or directory" errors.	 Why?
 5B.6	Why does "update" send all output to the terminal after 26 files
	have been updated?
 5B.7	Why does the merge occasionally resurrect lines of code?
 5B.8	Why does the merge fail when my "rcsmerge" program is
	configured to use GNU diff version 2.1 or later?


 **** Answers:

 5B.1	Why can't CVS handle deletion of directories?

	An oversight, probably.	 [[Fixed in a future release?]]


 5B.2	Why can't CVS handle the moving of sources from one place in the
	directory hierarchy to another?

	A "renaming database" has been proposed to track the history of
	pathname changes in the Repository.  A general solution is a
	difficult problem.  See 4B.8.


 5B.3	When I typed "cvs update -D <date>", why did it check out all
	sorts of ancient files from the Attic?	Shouldn't it just create
	the set of files and revisions that existed at that date?

	This seems to be a bug, but is really the lack of any obvious
	place to store the date when a file is "removed".

	There are four ranges of dates that CVS has to deal with when
	trying to determine what revision was available on <date>:

	1. Dates before the earliest revision in the file.

	2. Dates between any two revisions in the file.

	3. Dates between the latest revision in the file and the date
	   when the file was moved to the Attic by "commit".

	4. Dates after moving the file to the Attic.

	Since the date when a file is moved to the Attic is not stored
	anywhere, CVS can't tell the difference between #3 and #4.
	To avoid not producing a file that should exist in case #3, it
	produces extraneous files in case #4.


	For the above reason, if you have removed files in the Attic, it
	is better to use "-r <tag>, or even "-r HEAD" than to use a
	date spec.

	If you must use "-D <date>", then you should either archive and
	delete Attic files (losing some past history) or construct your
	Makefiles to work with an explicit list of files and let the old
	source files stay in the working directory.  The contents of the
	revision-controlled Makefile can then be considered to contain
	deletion "information".


 5B.4	When I typed "cvs update -D <date>" in my branch, why did it
	screw up all my files?

	Currently, the internal routine ("version_ts") that looks up
	info about a file,  overrides both the tag and date if *either*
	the tag or date is specified on the command line.  If only the
	date is specified, it should not override a branch tag, but it
	does.

	In CVS 1.3, the documented "-D <branch_tag>:<date>" syntax only
	works with the Main Branch and the Vendor Branch.

	[[Is this fixed in CVS 1.4?  This is one item I didn't check.]]


 5B.5	When I executed "checkout" into an existing directory I got "No
	such file or directory" errors.	 Why?

	Though the man page says that "checkout" turns into an
	"update -d" in directories that already exist, it is referring
	to directories that already exist *and* were created by CVS.

	When you try to run "checkout" on top of an existing directory
	structure, some of which wasn't created by CVS, it will handle
	directories and non-CVS files within directories already under
	CVS, but it will display the above error on non-CVS files within
	non-CVS directories.


 5B.6	Why does "update" send all output to the terminal after 26 files
	have been updated?

	CVS uses the "tmpnam()" function to generate temporary file names.
	The ANSI standard for the "tmpnam()" function says:

	"The tmpnam function generates a different string each time it is
	called, up to TMP_MAX times.  If it is called more than TMP_MAX
	times, the behavior is implementation defined."

	Later it says that the value of "TMP_MAX shall be at least 25."

	On some platforms, the above specification is taken literally by
	turning "at least 25" into "exactly 26" and by doing something
	foolish (i.e. "implementation defined") after that.  Some
	systems return the same name repeatedly, which causes one form of
	trouble.  Others return NULL or garbage, which causes a different
	form of trouble.

	The broken systems appear to be cycling a single character through
	the alphabet.  SunOS cycles 3 characters through the alphabet, so
	it won't cause trouble until 26 cubed or 17576 calls to
	"tmpnam()".

	Since CVS doesn't depend on the exact format of the tmp files, the
	workaround is to provide a "tmpnam()" that doesn't have a limit
	on the number of calls to it.


 5B.7	Why does the merge occasionally resurrect lines of code?

	The diff3 program provided by GNU diff version 1.15 has a bug
	that occasionally causes text to come back from the dead.

	This is an old problem which you can avoid by upgrading to the
	latest GNU "diffutils" package.	 If you were using GNU diff
	version 1.15 and plan to upgrade to the latest GNU diff program,
	see the next question.


 5B.8	Why does the merge fail when my "rcsmerge" program is
	configured to use GNU diff version 2.1 or later?

	A change in the overlap format was introduced in GNU diff3
	between versions 2.0 and 2.1 that causes RCS versions before
	5.6.0.1 to fail during a merge.

	To get consistent rcsmerge behavior, you have four choices:

	1. Go back to using GNU diff 1.15 or 2.0 with RCS versions 5.5 or
	   5.6.	 If you want to use GNU diff 2.1 or later, you'll have to
	   pick one of the other three choices in this list.

	2. Grab RCS version 5.6.0.1 from an FSF archive and set the
	   DIFF3_A macro to '1' as it tells you to in the Makefile:

		#define DIFF3_A 1

	3. Patch the RCS 5.6 source.  Change line 84 in "merger.c" from:

		DIFF3, "-am", "-L", label[0], "-L", label[1],
	   to
		DIFF3, "-amE", "-L", label[0], "-L", "", "-L", label[1],

	4. Wait both for RCS version 5.7 to be released and for a new
	   version of CVS that can deal with it.


----------------
-- Section 5C --	Development
----------------


 **** Questions:

 5C.1	Where do I send bug reports?
 5C.2	Where do I send fixes and patches?
 5C.3	Where do I send ideas for future development?
=5C.4	What plans are there for new features?
 5C.5	I have some time and I'd like to help.	What can I do for you?


 **** Answers:

 5C.1	Where do I send bug reports?

	First make sure it is a bug.  Talk to your friends, coworkers and
	anyone you know who uses CVS.  Search this FAQ for related issues.
	Then test it carefully.	 Try out variations to narrow down the
	problem.  Make sure it is repeatable.  Look for workarounds so you
	can report them.

	If you are still sure it's a bug and you tried to fix it, skip to
	the next question.  Otherwise, send a message to the info-cvs
	mailing list containing one of the following:

	1. If you have a good repeatable case and you think you know what
	   is going on, then describe the problem in detail.  Include
	   a workaround if you have one.

	2. If you have no idea what is going on, go ahead and send a
	   question to the info-cvs mailing list.  Include any information
	   you have describing the symptoms.


 5C.2	Where do I send fixes and patches?

	First make sure the "fix" does something useful.  Have someone
	review your fix.  Spend a bit of one person's time in a detailed
	analysis of your vast idea before displaying a half-vast idea to
	hundreds of people.

	If you tried to fix it and the patch is small, include the patch
	in your message.  Make sure the patch is based on the latest
	released version of CVS.

	If you tried to fix it and the patch is large, you should think
	about why it is so large.  Did you add a generally useful feature,
	or did it grow out of hand?

	If you still believe it is solid, produce a patch file using the
	CVS commands "patch" or "diff -c". [[You *are* keeping CVS under
	CVS, right?]]  The patch should be based on the latest released
	version of CVS.	 Then use the "cvsbug" program (provided with the
	CVS sources) to send it to the CVS maintainers.	 A self-contained
	patch that provides a single useful feature or correction might
	show up independently in the patches directory of the FTP archive.

	If careful testing reveals an RCS bug rather than a CVS bug, you
	can send bug reports to: rcs-bugs@cs.purdue.edu


 5C.3	Where do I send ideas for future development?

	If you have a bright idea, discuss it on the info-cvs mailing
	list.  If you have the time to implement something you can test,
	send the diffs along too as described above.


=5C.4	What plans are there for new features?

	A "rename" or "per-directory" database has been bandied about on
	the net for years.  It is needed, but it is a lot of work.

	CVS version 1.5 supports remote repository access, but Paul
	F. Kunz <Paul_Kunz@slac.stanford.edu> has produced another version
	(rCVS) that also runs remotely.  It is available for testing.

	    On the host "preprint.slac.stanford.edu", you can find:
		  Paper:	slacpubs/5000/slac-pub-5923.ps.Z

	    This was for a conference in Sept, 1993, before first beta.

	    On the host "ftp.slac.stanford.edu", you can find:
		  Sources:	pub/sources/rcvs-0.8.1.tar.Z

	   With the caveat that until version 1.0 is available, rCVS should
	   be considered an unreliable Beta release, you are invited to
	   grab a copy and test it.


	[[Others?]]


 5C.5	I have some time and I'd like to help.	What can I do for you?

	You can review this document, correct errors and fill in any of
	the incomplete sections.

	You can add to the contrib area, which contains useful ways to use
	some of the programmable CVS facilities (loginfo, commitinfo) or
	ways of connecting to work environments (pcl-cvs).

	You could write a regression test suite.  Or at least a scaffold
	into which we can drop tests.

	You can write specs for new features, fix bugs, review the man
	page or . . .

	[[Brian?]]

	[[Is there some way we can register someone as working
	  on something or should we just stay in the "implement it and
	  send it to me" mode?]]

----------------
-- Section 5D --	Professional Support
----------------


 **** Questions:

+5D.1	Doesn't Cygnus support CVS?
+5D.2	What is Cyclic Software doing with CVS?


 **** Answers:

+5D.1	Doesn't Cygnus support CVS?

	Cygnus is a company that supports a variety of FSF software.  It
	uses a version of CVS and people from Cygnus are on the info-cvs
	mailing list.

	[[Could someone from Cygnus state Cygnus's official and unofficial
	  relationship with CVS?]]


+5D.2	What is Cyclic Software doing with CVS?

	Cyclic Software exists to provide support for CVS.  Here's a copy
	of their product line sheet:


				    Cyclic Software
				   Standard Support

	   Cyclic Software offers support contracts for CVS.  This
	includes:

	   * Full source, binaries, and documentation for CVS, RCS, GNU
	     diffutils, patch, and gzip -- that is, CVS and everything it
	     wants to run -- via FTP or tape;

	   * guaranteed responses for bugs within 5 business days;

	   * guaranteed fixes for reproducible bugs within 10 business days.

	     (By "reproducible bugs", we mean instances where the software
	     clearly does not behave as documentation or reasonable
	     expectations indicate it should, and that we are able to
	     reproduce this misbehavior reliably.  Naturally, we will make
	     every possible effort to reproduce the bugs you report; our
	     experience has been that it's usually not difficult.)

	   We charge a fixed fee for:

	   * one year

	   * one host type (hardware & operating system)

	   * twenty users at your site, with two of those users designated
	     as "contacts" for CVS, to reduce communication problems.

	   If the host type is not one we have access to for testing
	purposes, you can either lend us a machine of the appropriate type
	for the duration of the contract, or pay an additional fee
	up-front.  We have access to Solaris, Irix, HP-UX, Linux and
	Ultrix.  (This list is subject to change; contact us for details.)

	   If the above fee structure is not well-suited to your
	organization, please say so.  We're interested in tailoring our
	services to be as useful to you as possible.

				       Training

	   We offer on-site training in the use of CVS at a daily rate,
	plus expenses (inc. travel, accommodations).  The classes target
	new and intermediate users of CVS; we feel advanced users benefit
	more from a written manual and the source code.

				  Custom Enhancements

	   We will implement enhancements to CVS or its documentation, and
	port CVS to new architectures.  Our rates for this work depend on
	the amount of work to be done.

	   We strongly prefer to work on enhancements suitable for
	incorporation into the general CVS release upon completion; we
	will help you design the enhancement in a way that makes this
	possible.

				 Short-Term Consulting

	   We will do short-term consulting at hourly rates.  These rates
	are calculated to include the overhead of dealing in short time
	periods.  Therefore, in sufficiently large projects, we recommend
	arranging a long-term support contract instead of dealing on an
	hourly basis.

				     Anything Else

	   Cyclic Software is interested in arranging contracts for work
	in other areas, to be produced as free software.  Everything is
	negotiable.

				   How To Contact Us

	     (Email is preferred.)

	     Email:     <info@cyclic.com>
	     Phone:     +1 812 335 9023
	     Web:       http://www.cyclic.com
	     SnailMail: Cyclic Software
			P.O. Box 804
			Bloomington, IN 47402-0804
			USA

				Contributed by Jim Blandy



=================================================
==  Section 6	====	Table of Contents    ====
=================================================

===========================================================================
== Frequently Asked Questions about CVS (The Concurrent Versions System) ==
===========================================================================

============================================
==  Section 0	====	Introduction	====
============================================

Questions are divided into five numbered Sections.  Sections are divided
into lettered sub-sections.  The questions are numbered sequentially
within each sub-section, though they are in no particular order.

	1. What is CVS?
	   A. What is CVS?  What's it for?  Why CVS?
	   B. Where do I find it?  Where can I find Help?
	   C. How does CVS differ from other similar software?
	   D. What do you mean by .  .	.? (Definitions)

	2. User Tasks
	   A. Getting Started
	   B. Common User Tasks
	   C. Less Common User Tasks
	   D. General Questions

	3. Commands
	   A. through P.  One section for each CVS command.

	4. Advanced Topics
	   A. Installing CVS
	   B. Setting up and Managing the Repository
	   C. Branching and Merging
	   D. Tricks of the Trade
	   E. Internal errors
	   F. Related Software
	   G. Engineering
	   H. Other Systems

	5. Past & Future
	   A. Contributors.
	   B. Bugs and Patches
	   C. Development
	   D. Professional Support

	6. Table of Contents



============================================
==  Section 1	====	What is CVS?	====
============================================

----------------
-- Section 1A --	What is CVS?  What's it for?  Why CVS?
----------------
 1A.1	What does CVS stand for?  Can you describe it in one sentence?
 1A.2	What is CVS for?  What does it do for me?
 1A.3	How does CVS work?
 1A.4	What is CVS useful for?
 1A.5	What is CVS *not* useful for?

----------------
-- Section 1B --	Where do I find CVS?  Where can I find Help?
----------------
 1B.1	How do I get more information about CVS?
 1B.2	Is there an archive of CVS material?
 1B.3	How do I get files out of the archive if I don't have FTP?
 1B.4	How do I get a copy of the latest version of CVS?
 1B.5	Is there a mailing list devoted to CVS?	 How do I find it?
 1B.6	What happened to the CVS Usenet newsgroup I heard about?

----------------
-- Section 1C --	How does CVS differ from other, similar software?
----------------
 1C.1	How does CVS differ from RCS?
 1C.2	How does CVS differ from SCCS?
 1C.3	How does CVS differ from ClearCase?
#1C.4	How does CVS differ from TeamWare/SparcWorks?
 1C.5	How does CVS differ from Aegis?
 1C.6	How does CVS differ from Shapetools?
 1C.7	How does CVS differ from TeamNet?
 1C.8	How does CVS differ from ProFrame?
 1C.9	How does CVS differ from CaseWare/CM?
 1C.10	How does CVS differ from Sublime?
 1C.11	How does CVS differ from PVCS?
 1C.12	How does CVS differ from CMVC?

----------------
-- Section 1D --	What do you mean by . . .? (Definitions)
----------------
 1D.1	What are "The Repository", "$CVSROOT" and "CVSROOT"?
 1D.2	What is an RCS file?
 1D.3	What is a working file?
 1D.4	What is a working directory (or working area)?
 1D.5	What is "checking out"?
 1D.6	What is a revision?
 1D.7	What is a "Tag"?
 1D.8	What are "HEAD" and "BASE"?
 1D.9	What is a Branch?
 1D.10	What is "the trunk"?
 1D.11	What is a module?
 1D.12	What does "merge" mean?


==========================================
==  Section 2	====	User Tasks    ====
==========================================

----------------
-- Section 2A --	Getting Started
----------------
 2A.1	What is the first thing I have to know?
 2A.2	Where do I work?
 2A.3	What does CVS use from my environment?
 2A.4	OK, I've been told that CVS is set up, my module is named
	"ralph" and I have to start editing.  What do I type?
 2A.5	I have been using RCS for a while.  Can I convert to CVS without
	losing my revision history?  How about converting from SCCS?

----------------
-- Section 2B --	Common User Tasks
----------------
 2B.1	What is the absolute minimum I have to do to edit a file?
 2B.2	If I edit multiple files, must I type "commit" for each one?
 2B.3	How do I get rid of the <module> directory that "checkout" created?
 2B.4	How do I find out what has changed since my last update?
 2B.5	I just created a new file.  How do I add it to the Repository?
 2B.6	How do I merge changes made by others into my working directory?
 2B.7	How do I label a set of revisions so I can retrieve them later?
 2B.8	How do I checkout an old release of a module, directory or file?
 2B.9	What do I have to remember to do periodically?

----------------
-- Section 2C --	Less Common User Tasks
----------------
 2C.1	Can I create non-CVS sub-directories in my working directory?
 2C.2	How do I add new sub-directories to the Repository?
 2C.3	How do I remove a file I don't need?
 2C.4	How do I rename a file?
 2C.5	How do I make sure that all the files and directories in my
	working directory are really in the Repository?
 2C.6	How do I create a branch?
 2C.7	How do I modify the modules file?  How about the other files in
	the CVSROOT administrative area?
 2C.8	How do I split a file into pieces, retaining revision histories?

----------------
-- Section 2D --	General Questions
----------------
 2D.1	How do I see what CVS is trying to do?
 2D.2	If I work with multiple modules, should I check them all out and
	commit them occasionally?  Is it OK to leave modules checked out?
 2D.3	What is a "sticky" tag? What makes it sticky? How do I loosen it?
 2D.4	How do I get an old revision without updating the "sticky tag"?
 2D.5	What operations disregard sticky tags?
 2D.6	Is there a way to avoid reverting my Emacs buffer after
	committing a file?  Is there a "cvs-mode" for Emacs?
 2D.7	How does conflict resolution work?  What *really* happens if two
	of us change the same file?
 2D.8	How can I tell who has a module checked out?
 2D.9	Where did the .#<file>.1.3 file in my working directory come from?
 2D.10	What is this "ignore" business?	 What is it ignoring?
 2D.11	Is there a way to set user-specific configuration options?
 2D.12	Is it safe to interrupt CVS using Control-C?
 2D.13	How do I turn off the "admin" command?
 2D.14	How do I turn off the ability to disable history via "cvs -l"?
 2D.15	How do I keep certain people from accessing certain directories?


========================================
==  Section 3	====	Commands    ====
========================================

----------------
-- Section 3A --	"add", "ad", "new"
----------------
 3A.1	What is "add" for?
 3A.2	How do I add a new file to the branch I'm working on?
 3A.3	Why did my new file end up in the Attic?
 3A.4	Now that it's in the Attic, how do I connect it to the Main branch?
 3A.5	How do I avoid the hassle of reconnecting an Attic-only file to
	the Main Branch?
 3A.6	How do I cancel an "add"?
 3A.7	What are the ./CVS/file,p and ./CVS/file,t files for?
 3A.8	How do I "add" a binary file?

----------------
-- Section 3B --	"admin", "adm", "rcs"
----------------
 3B.1	What is "admin" for?
 3B.2	Wow!  Isn't that dangerous?
 3B.3	What would I normally use "admin" for?
 3B.4	What should I avoid when using "admin"?
 3B.5	How do I restrict the "admin" command?	The -i flag in the modules
	file can restrict commits.  What's the equivalent for "admin"?
 3B.6	I backed out a revision with "admin -o" and committed a
	replacement.  Why doesn't "update" retrieve the new revision?

----------------
-- Section 3C --	"checkout", "co", "get"
----------------
 3C.1	What is "checkout" for?
 3C.2	What is the "module" that "checkout" takes on the command line?
 3C.3	Isn't a CVS "checkout" just a bunch of RCS checkouts?
 3C.4	What's the difference between "update" and "checkout"?
 3C.5	Why can't I check out a file from within my working directory?
 3C.6	How do I avoid dealing with those long relative pathnames?
 3C.7	Can I move a checked-out directory?  Does CVS remember where it
	was checked out?
 3C.8	How can I lock files while I'm working on them the way RCS does?
 3C.9	What is "checkout -s"?	How is it different from "checkout -c"?

----------------
-- Section 3D --	"commit", "ci", "com"
----------------
 3D.1	What is "commit" for?
 3D.2	If I edit ten files, do I have to type "commit" ten times?
 3D.3	Explain: cvs commit: Up-to-date check failed for `<file>'
 3D.4	What happens if two people try to "commit" conflicting changes?
 3D.5	I committed something and I don't like it.  How do I remove it?
 3D.6	Explain: cvs commit: sticky tag `V3' for file `X' is not a branch
 3D.7	Why does "commit -r <tag/rev>" put newly added files in the Attic?
 3D.8	Why would a "commit" of a newly added file not produce rev 1.1?

----------------
-- Section 3E --	"diff", "di", "dif"
----------------
 3E.1	What is "diff" for?
 3E.2	Why did "diff" display nothing when I know there are later
	committed revisions in the Repository?
 3E.3	How do I display what changed in the Repository since I last
	executed "checkout", "update" or "commit"?
 3E.4	How do I display the difference between my working file and what
	I checked in last Thursday?
 3E.5	Why can't I pass long options, like --unified, to "diff"?

----------------
-- Section 3F --	"export", "exp", "ex"
----------------
 3F.1	What is "export" for?
 3F.2	Why does it remove the RCS keywords so I can't use the "ident"
	command on the source files?
 3F.3	Can I override the '-kv' flag CVS passes to RCS?
 3F.4	Why doesn't "export" have a '-k' flag like "import" does?
 3F.5	Why does "export -D" check out every file in the Attic?

----------------
-- Section 3G --	"history", "hi", "his"
----------------
 3G.1	What is "history" for?
 3G.2	Of what use is it?
 3G.3	What is this, Big Brother?
 3G.4	I deleted my working directory and "history" still says I have
	it checked out.	 How do I fix it?
 3G.5	So I *can* edit the History file?
 3G.6	Why does the history file grow so quickly?
 3G.7	What is the difference between "cvs history -r <tag/rev>" and
	"cvs history -t <tag>"?
 3G.8	Why does "cvs history -c -t <tag>" fail to print anything?
 3G.9	"cvs history -a -o" only printed one line for each checked-out
	module.	 Shouldn't it print all the directories where the
	modules are checked out?
 3G.10	I can't figure out "history", can you give me concrete examples?
 3G.11	Can we merge history files when we merge Repositories?

----------------
-- Section 3H --	"import", "im", "imp"
----------------
 3H.1	What is "import" for?
 3H.2	How am I supposed to use "import"?
 3H.3	Why does import put files on a branch?	Why can't I work on the
	main trunk instead of a Vendor branch?
 3H.4	Is there any way to import binary files?
 3H.5	Why does "import" corrupt some binary files?
 3H.6	How do I retain the original $\Revision$ strings in the sources?
=3H.7	I imported some files for the Yarg compiler that compiles files
	with a suffix of ".yarg" and whose comment prefix is "YARG> ".
	When I check them out, they will no longer compile because they
	have this junk in them.	 Why?
 3H.8	How do I make "import" save the timestamps on the original files?
 3H.9	Why can't I "import" 3 releases on different branches?
 3H.10	What do I do if the Vendor adds or deletes files between releases?
 3H.11	What about if the Vendor changes the names of files or
	directories, or rearranges the whole structure between releases?
 3H.12	I thought "import" was for Vendor releases, why would I use it
	for code of my own?  Do I have to use import?
 3H.13	How do I import a large Vendor release?
 3H.14	Explain: ERROR: cannot create link to <file>: Permission denied
 3H.15	Where does the -m <message> go when the file doesn't change?
 3H.16	How do I "import" just the files ignored by a previous "import"?
 3H.17	Why did "import" ignore all the symlinks?

----------------
-- Section 3I --	"log", "lo", "rlog"
----------------
 3I.1	What is "log" for?
 3I.2	How do I extract the log entries between two revisions?
 3I.3	How do I extract the log entries on a whole branch?
 3I.4	How do I generate ChangeLogs from RCS logs?
 3I.5	Why does "log" tell me a file was committed exactly 5 hours later
	than I know it was?

----------------
-- Section 3J --	"patch", "pa", "rdiff"
----------------
 3J.1	What is "patch" for?
 3J.2	Why does "patch" include files from the Attic when I use '-D'?
 3J.3	How do I make "patch" produce a patch for one or two files?
	It seems to work only with modules.

----------------
-- Section 3K --	"release", "re", "rel"
----------------
 3K.1	What is "release" for?
 3K.2	Why can't I reverse a "cvs checkout path/name/subdir" with a
	"cvs release path/name/subdir" without an "unknown module name"?
 3K.3	Why can't I "release" portions of a checked out directory?  I
	should be able to "release" any file or sub-directory within
	my working directory.
 3K.4	I removed the tree that I was about to start working on.  How do I
	tell cvs that I want to release it if I don't have it anymore?
 3K.5	Why doesn't "release -d module" reverse a "checkout module"?
 3K.6	Why can't I release a module renamed with "cvs checkout -d"?

----------------
-- Section 3L --	"remove", "rm", "delete"
----------------
 3L.1	What is "remove" for?
 3L.2	Why doesn't "remove" work on directories when it appears to try?
 3L.3	I don't like removing files.  Is there another way to ignore them?
 3L.4	I just removed a file.	How do I resurrect it?
 3L.5	Why doesn't "remove" delete the file?  Instead, it prints an
	error message and tells me to remove the file by hand.

----------------
-- Section 3M --	"rtag", "rt", "rfreeze"
----------------
 3M.1	What is "rtag" for?
 3M.2	Why use "rtag"?	 It assumes no one is changing the Repository.
 3M.3	What revision does "rtag -r <tag1> <tag2>" actually put the tag on?
 3M.4	What happens if the tags are the same in "rtag -r <tag> <tag>"?
 3M.5	Why doesn't "rtag -b -r <branch_tag1> <branch_tag2>" rename or
	duplicate a magic branch tag?

----------------
-- Section 3N --	"status", "st", "stat"
----------------
 3N.1	What is "status" for?
 3N.2	Why does "status" limit the File: at the top to 17 characters?
 3N.3	Why does it print "Sticky" lines when the values are "(none)"?
 3N.4	Shouldn't the status "Needs Checkout" be "Needs Update"?

----------------
-- Section 3O --	"tag", "ta", "freeze"
----------------
 3O.1	What is "tag" for?
 3O.2	What is the difference between "tag" and "rtag"?
 3O.3	Why does "tag -b" not put a tag on the Branch Point revision?
	How do I refer to the Branch Point?
 3O.4	So "{r}tag" labels a bunch of files.  What do you use a Tag for?
 3O.5	How do I get "tag" and "rtag" to send mail the way "commit" does?
 3O.6	Why can't "tag" handle the '-r' option that "rtag" takes?
 3O.7	After a "tag <tag>" in my working directory, why doesn't "checkout
	-r <tag>" somewhere else produce copies of my current files?
 3O.8	Why doesn't "tag" write a history record the way "rtag" does?
 3O.9	How do I rename a <tag>?

----------------
-- Section 3P --	"update", "up", "upd"
----------------
 3P.1	What is "update" for?
 3P.2	What do 'U', 'M' and 'C' mean when I type "update"?  Are they
	different for "cvs -n update"?
 3P.3	What's the difference between "update" and "checkout"?
 3P.4	Why don't I get new files when I execute "update"?
 3P.5	Why does "update" say 'M' both for plain modified files and for
	successful (i.e. conflict-free) merges?	 Aren't they different?
 3P.6	What's a "sticky conflict"?  How does it know a conflict occurred?
 3P.7	Is there a feature to tell me what I have changed, added and
	removed without changing anything?
 3P.8	Why were all my files deleted when I executed "update"?


===============================================
==  Section 4	====	Advanced Topics	   ====
===============================================

----------------
-- Section 4A --	Installing CVS
----------------
 4A.1	What do I have to do before I install CVS?
 4A.2	How do I configure the CVS programs?
 4A.3	What do I have to install?
 4A.4	How do I work around the merge problems in GNU diff version 2.1
	or later?

----------------
-- Section 4B --	Setting up and Managing the Repository
----------------
 4B.1	What do I do first?  How do I create a Repository?
 4B.2	What are those files in $CVSROOT/CVSROOT?
 4B.3	Is there any other state stored in the Repository besides in the
	$CVSROOT/CVSROOT directory?
 4B.4	How do I put sources into the Repository?
 4B.5	What file permissions should I use on (and in) the Repository?
 4B.6	How do I structure my Repository?
 4B.7	Why would anyone use "modules"?	 They are too restrictive.  I
	want to be able to select just the files I want to edit.
 4B.8	How do I rename a file or directory?  What are the consequences?
 4B.9	What are "Attic" directories?
 4B.10	Is it OK to remove anything from the Repository?
 4B.11	Can I convert to CVS from RCS without losing my revision history?
 4B.12	Can I move RCS files with branches in them into the Repository?
 4B.13	Can I use raw RCS commands on the Repository?
 4B.14	How do I convert from SCCS to RCS?
 4B.15	How do I limit access to the Repository?
 4B.16	What are the Repository Administrator's responsibilities?
 4B.17	How do I move the whole Repository?
 4B.18	How do I change permissions on a file in the Repository by using
	a CVS command?	(i.e. without using "chmod 777 $CVSROOT/dir/file")

----------------
-- Section 4C --	Branching and Merging
----------------
 4C.1	What is a branch?
 4C.2	Why (or when) would I want to create a branch?
 4C.3	How do I create and checkout a branch?
 4C.4	Once created, how do I manage a branch?
 4C.5	Are there any extra issues in managing multiple branches?
 4C.6	How do I merge a whole branch back into the trunk?
=4C.7	How do I merge changes from the trunk into my branch or between
	branches?
 4C.8	How do I merge onto the Main Branch a file that exists only on a
	branch other than the Main Branch?  (i.e. it is in the Attic)
 4C.9	How do I know what branch I'm (working) on?
 4C.10	Do I really have to know the name of the branch I'm working on?
 4C.11	How do I refer to the revision where I branched so I can see
	what changed since the Branch Point on another branch?
 4C.12	Why didn't the command "cvs admin -bBRANCH1 *" create a branch?
 4C.13	Is it possible to set the "default CVS branch" for everyone?
 4C.14	How do I perform a large merge?
 4C.15	Is a Vendor merge any different from a branch merge?
 4C.16	How do I go back to a previous version of the code on a branch?
 4C.17	Once I've found the files I want, how do I start changing them?
	I keep getting warnings about sticky tags.
 4C.18	Why do I get the latest files on the branch when I tried to
	"update -r <tag>"?
 4C.19	How can I avoid a merge?  I just want to move the latest revision
	on my working branch directly onto the trunk.
 4C.20	How to I avoid merge collisions in the RCS $\Log$ data?
 4C.21	Why should I trust automatic merges?
 4C.22	How does CVS decide if it can safely perform a merge?
 4C.23	After resolving merge conflicts in a file, what if I want to keep
	my previous version, and not take any of the branch changes?

----------------
-- Section 4D --	Tricks of the Trade
----------------
 4D.1	How can you even check in binary files, let alone allow CVS to
	do its auto-merge trick on them?
 4D.2	Can I edit the RCS (",v") files in the Repository?
 4D.3	Can I edit the ./CVS/{Entries,Repository,Tag} files?
 4D.4	Someone executed "admin -o" and removed revisions to which
	tags/symbols were attached.  How do I fix them?
 4D.5	How do I move or rename a magic branch tag?
 4D.6	Can I use RCS locally to record my changes without making them
	globally visible by committing them?
 4D.7	How can I allow access to the Repository by both CVS and RCS?
 4D.8	I "updated" a file my friend, "bubba", committed yesterday.
	Why doesn't the file now have a modified date of yesterday?
 4D.9	While in the middle of a large "commit", how do I run other
	commands, like "diff" or "stat" without seeing lock errors?
 4D.10	Where did the ./CVS/Entries.Static file come from?  What is it for?
 4D.11	Why did I get the wrong Repository in the loginfo message?
 4D.12	How do I run CVS setuid so I can only allow access through the
	CVS program itself?
 4D.13	How about using groups and setgid() then?
 4D.14	How do I use the "commitinfo" file?
 4D.15	How do I use the "loginfo" files?
 4D.16	How can I keep people with restrictive umask values from blocking
	access to the Repository?
 4D.17	Why do timestamps sometimes get set to the date of the revision,
	sometimes not?	The inconsistency causes unnecessary recompiles.

----------------
-- Section 4E --	Internal errors
----------------
 4E.1	Explain: "ci error: unexpected EOF in diff output"
 4E.2	Explain: "RCS file /Repository/module/file.c,v is in use"
 4E.3	Explain: "co error, line 2: Missing access list"
 4E.4	Explain: "error: RCS file name `xyz .c' contains white space"
 4E.5	Explain: cvs checkout: warning: <X> is not (any longer) pertinent
 4E.6	Why did a Repository file change from <file>,v to ,<file>,?

----------------
-- Section 4F --	Related Software
----------------
 4F.1	How do I use CVS under Emacs?  Is there an Emacs cvs-mode?
 4F.2	What is GIC (Graphical Interface to CVS)?
 4F.3	What is CAVEMAN?

----------------
-- Section 4G --	Engineering
----------------
 4G.1	Where can I find out about Software Engineering?
 4G.2	How do I flexibly arrange the modules file to describe my sources?
 4G.3	Can I have multiple source repositories, one for each project?
 4G.4	Who should administer the Repository and manage the modules file?
 4G.5	Isn't disk space a big factor?	CVS copies files out of the
	Repository, duplicating everything.

----------------
-- Section 4H --	Other Systems
----------------
 4H.1	I use a NeXT.  Is there anything I need to know?
 4H.2	I use OS/2 and/or DOS.	Is there anything I need to know?
 4H.3	I use SCO Unix.	 Is there anything I need to know?
 4H.4	I use AIX.  Is there anything I need to know?
 4H.5	I use IRIX.  Is there anything I need to know?
 4H.6	I use an HP system.  Is there anything I need to know?
 4H.7	I use AFS.  Is there anything I need to know?
 4H.8	I use A/UX.  Is there anything I need to know?


=============================================
==  Section 5	====	Past & Future	 ====
=============================================

----------------
-- Section 5A --	Contributors
----------------
=5A.1	Who wrote CVS?
 5A.2	You didn't write all of this FAQ, did you?

----------------
-- Section 5B --	Bugs and Patches
----------------
 5B.1	Why can't CVS handle deletion of directories?
 5B.2	Why can't CVS handle the moving of sources from one place in the
	directory hierarchy to another?
 5B.3	When I typed "cvs update -D <date>", why did it check out all
	sorts of ancient files from the Attic?	Shouldn't it just create
	the set of files and revisions that existed at that date?
 5B.4	When I typed "cvs update -D <date>" in my branch, why did it
	screw up all my files?
 5B.5	When I executed "checkout" into an existing directory I got "No
	such file or directory" errors.	 Why?
 5B.6	Why does "update" send all output to the terminal after 26 files
	have been updated?
 5B.7	Why does the merge occasionally resurrect lines of code?
 5B.8	Why does the merge fail when my "rcsmerge" program is
	configured to use GNU diff version 2.1 or later?

----------------
-- Section 5C --	Development
----------------
 5C.1	Where do I send bug reports?
 5C.2	Where do I send fixes and patches?
 5C.3	Where do I send ideas for future development?
=5C.4	What plans are there for new features?
 5C.5	I have some time and I'd like to help.	What can I do for you?

----------------
-- Section 5D --	Professional Support
----------------
+5D.1	Doesn't Cygnus support CVS?
+5D.2	What is Cyclic Software doing with CVS?


=================================================
==  Section 6	====	Table of Contents    ====
=================================================

% End of Table of Contents
% End of CVS FAQ document

# Local Variables:
# mode: text
# fill-column: 74
# fill-prefix: "\t"
# End: