hardenedbsd/HardenedBSD
1
0
Fork 0
mirror of https://git.hardenedbsd.org/hardenedbsd/HardenedBSD.git synced 2024-11-18 17:00:49 +01:00
Code Issues Actions Packages Projects Releases Wiki Activity
668eb4585f
HardenedBSD/gnu/usr.bin/cvs/FAQ

7827 lines
271 KiB
Plaintext
Raw Blame History

This file contains invisible Unicode characters

This file contains invisible Unicode characters that are indistinguishable to humans but may be processed differently by a computer. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

Archive-name: cvs-faq
$Revision: 1.1 $ <<== Include this in your comments
$Date: 1994/10/07 06:17:45 $
===========================================================================
== 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:
Though every 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@think.com>
To help readers of previous versions of this document, I will annotate
each question with a change marker
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.
The markers indicate significant changes in content between major
revision numbers. Trivial changes, such as question reordering or
spelling and grammar corrections are not marked. If I need to delete
a question, I'll move it to a "Deleted" section for a few revisions.
Deletions will arise when new versions of CVS are released. In the
long run, any question that can be answered by "get the latest
release" will be deleted.
The minor revision number will change frequently. If a minor revision
change is large enough, I'll add a change marker. At major revision
changes the markers will be cleared and set again, based on the latest
minor revision of the previous major revision.
Editorial comments are delimited by pairs of "[[" & "]]". They
contain either references to the (usually unfinished) nature of the
FAQ entry itself or version-specific comments to be removed (or
altered) when new revisions of CVS are released.
You may redistribute this as long as you don't take statements out
of context. Keep it together along with the revision number.
============================================
== 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
D. Tricks of the Trade
E. Weirdness
F. Related Software
G. Other Systems
5. Past & Future
A. Contributors.
B. Bugs and Patches
C. Development
6. Table of Contents
Final note:
Except for the "Past & Future" section, all answers in this
document refer to the latest released version of CVS: 1.3.
============================================
== 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?
=1A.6 Why isn't it called OSCO (Online Source COntrol)?
**** 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 changes to files 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 stores its files 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 the "checkout" command, handing it
a module or directory you want to work on. CVS copies each file
in the specified module or directory out of the Repository and
into a sub-directory created in your current directory.
You may then modify files in the new sub-directory, building them
into output files and testing 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"
can produce 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 be useful for three major activities:
1. Multiple developers
The major advantage of using CVS over the older and 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 point 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. Vendor releases
If you are making changes to a product distributed by someone
else, the CVS feature, called the Vendor Branch, allows you
to combine local modifications with 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 require medium amounts of
work. (e.g. GNU programs, X, etc.)
3. Branches
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.)
Although, at this writing, CVS's branch support is a bit
primitive, CVS was designed to allow you to create branches,
work on them for while and merge them back into the main
line of development. 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. 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 write your Makefiles or
scripts in every directory so they have to know the relative
positions of everything else, you wind up requiring the entire
Repository to be checked out. 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 place the tools created to support such
a build system (scripts, Makefiles, etc) under CVS.
CVS is not a substitute for management.
Your managers and project leaders are expected to talk to
you frequently enough to make certain you are aware of
schedules, merge points, branch names and release dates. If
they don't, CVS can't help.
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 (i.e. "diff3") command.
CVS does not claim to help at all in figuring out non-textual
or distributed conflicts in program logic.
For example: Say you change the arguments to function X
defined in file A. At the same time, someone edits 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.
=1A.6 Why isn't it called OSCO (Online Source COntrol)?
Better discount? CVS is shorter? (The international audience
requires an explanation: Both CVS and OSCO are the names of large
chains of Pharmacies (drug stores) in the U.S.)
----------------
-- 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 a copy of the latest version of CVS?
1B.4 Is there any other documentation? How about tutorials?
1B.5 Is there a mailing list devoted to CVS? How do I get on it?
1B.6 What prayers are appropriate for each of the major denominations
(e.g. 20's, 50's, 100's) when issuing complex CVS commands?
+1B.7 How do I get files out of the archive if I don't have FTP?
**** Answers:
=1B.1 How do I get more information about CVS?
1. The first thing you should do is read the man page.
2. Type "cvs -H" for general help or "cvs -H command" for
command-specific help.
3. Read the original CVS paper (in the source tree, under "doc").
It describes the purpose of CVS and some of its workings. Note
that some of the emphasis (especially on multiple vendors
providing the same sources) is out of date.
4. Read the man pages for RCS.
5. Read the source code.
6. Look in the "doc" directory in the FTP archive described
below.
7. Read the gnu.cvs.info newsgroup.
8. If you don't get the newsgroup, you can 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 documentation, patches and
the latest release.
ftp think.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.
+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. To use DEC's ftpmail service, type
echo 'send help' | mail ftpmail@decwrl.dec.com
which will send you a message telling you how to use Email to
retrieve files from FTP archives.
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@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 is
another archive at UUNET and other large Internet sites.
Program(s) Latest revision
----------- -----------------------
CVS 1.3
RCS 5.6.0.1
GNU diff 2.3
The GNU version of diff is suggested by both the RCS and CVS
configuration instructions because it works better than the
standard version. If you plan to use dbm in the modules file, you
might also want to pick up the GNU dbm library.
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 probably want.
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 any other documentation? How about tutorials?
Take a look at the "doc" sub-directory in the FTP archive.
You should find a growing collection of additional CVS
documentation there.
Other sources:
1. Per Cederqvist's Texinfo manual.
The latest version of the Texinfo manual written by Per
Cederqvist is included in the "doc" area mentioned
above.
2. Gray Watson's cvs_tutorial.
There is a version of this document in the "doc" area.
3. Apparently there is at least one project at O'Reilly (on
RCS/SCCS) that will include some info about CVS.
[[Anything else?]]
#1B.6 Is there a mailing list or Usenet newsgroup devoted to CVS?
How do I find them?
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. An
associated Usenet newsgroup named "gnu.cvs.info" was created in
August, 1993.
The newsgroup and the mailing list are bidirectionally gatewayed,
meaning that you only need access to one of them. Anything sent
to the mailing list will be automatically posted to "gnu.cvs.info"
and anything posted to the newsgroup will be automatically mailed
to "info-cvs".
First try the newsgroup, since it is generally easier to read (and
manage) than a mailing list. Ask your system administrator
whether you get the "gnu" hierarchy. If so, select a newsreader
and dive in.
If you don't get any form of Usenet News (or don't get the "gnu"
hierarchy), 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 and the newsgroup might appear
someday in the CVS FTP archive.
1B.7 What prayers are appropriate for each of the major denominations
(e.g. 20's, 50's, 100's) when issuing complex CVS commands?
Only what the traffic will allow, in small, unmarked bills
delivered to me, Ralph Icebag, in a plain brown wrapper, by a
brown-shoed square, in the dead of night. (Apologies to
Firesign Theater.)
----------------
-- 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?
1C.5 How does CVS differ from SunPro?
1C.6 How does CVS differ from Aegis?
1C.7 How does CVS differ from Shapetools?
+1C.8 How does CVS differ from TeamNet?
+1C.9 How does CVS differ from ProFrame?
+1C.10 How does CVS differ from CaseWare/CM?
+1C.11 How does CVS differ from Sublime?
**** 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
whole sets of files on the command line, but groups are
manipulated by iterating over those files. There is no pretense
of combined interaction between the 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 client-server CASE tool for version management,
configuration management, and process management. ClearCase
is an evolution of the popular DSEE tools, formerly available
on HP/Apollo platforms. ClearCase includes an X/Motif GUI,
command-line interface, and C programmer API, and is currently
available on Sun, HP, and SGI platforms.
ClearCase uses a special Unix filesystem type, called "mfs"
for "multi-version file system". Conceptually, mfs adds
another dimension to the regular Unix filesystem. The new
axis is used to store the different versions of files. Each
user makes a "view" into the file database by creating a
special mfs mountpoint on their machine. Each view has a set
of flexible selection rules that specify the particular
version of each file to make visible in that view. You can
think of a "view" as a workarea in CVS, except that the files
don't really exist on your local disk until you modify them.
This type of filesystem is sometimes called "copy-on-write"
and conserves disk space for files that are read-only.
Another advantage is that a view is "tranparent" 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 and
the checkin/checkout development model with file locking.
Directories are versionable objects as well as files. A
graphical n-way merge tool is provided. Like CVS, 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 Makefiles 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. Hyperlinks between versioned 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)
Contributed by Steve Turner
[extracted from the ClearCase 1.1.1 documentation]
=1C.4 How does CVS differ from TeamWare?
TeamWare is a configuration management tool from Sun
Microsystems.
For more information, contact:
SunExpress, Inc.
P.O. Box 4426
Bridgeton, MO 63044-9863
(800)873-7869
1C.5 How does CVS differ from SunPro?
SunPro is advertised as the successor to "SCCS".
[[Need more info here.]]
1C.6 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.7 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 versioned 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.8 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.9 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 RS600, 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.10 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.11 How does CVS differ from Sublime?
Produced by AT&T.
[[Need more info here.]]
----------------
-- 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.
1D.2 What is an RCS file?
A file, usually ending in ",v", 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.
1D.3 What is a working file?
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)?
The "checkout" command creates a tree of working directories,
filling them with working files. A working directory always
contains a sub-directory named ./CVS containing information
about working files and the location of the directory within the
Repository that was used to create the working directory.
A working directory is the place where you work and the place
from which you "commit" files.
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. See the "checkout" command in Section 3C.
=1D.6 What is a revision?
A "revision" is a version of a file that was "committed" (or
"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" (or 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.
=1D.8 What are "HEAD" and "BASE"?
BASE and HEAD 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
become different for two reasons:
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 by executing "update -A".
=1D.9 What is a Branch?
Any mechanism that allows one or more developers to modify a
physically separate copy of a file without affecting anyone other
than those working on the branch.
There are four kinds of branches CVS deals with:
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 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, the
purpose and the way it is managed are different. The major
difference is that the branch is 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 the 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 must be *files*.
No directories, no relative pathnames. To checkout more
than one directory by a single name, use an alias as
described in #5 below.
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 /emacs.helper gnu/emacs
The files checked out are exactly the same as the files you
would get 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 /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.
Example:
my_work -a emacs gnu/bison unix/bin/ls.c
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.
As an example, say you want to keep track of three programs, and
want to be allowed to check out any combination of one, two or all
three at a time. Here are most of the combinations I can think
of. Experiment and choose what you want -- you won't need every
possibility.
# All directories in "world", even ones added later.
world world
# All three programs by name. They checkout into local dir.
prog123 -a prog1 prog2 prog3
# All three programs by name. They checkout into "world" subdir.
wprog123 -a wprog1 wprog2 wprog3
# Individual progs checkout into dirs named "prog1", etc.
prog1 world/prog1
prog2 world/prog2
prog3 world/prog3
# Individual progs checkout into dirs named "world/prog1", etc.
wprog1 -a world/prog1
wprog2 -a world/prog2
wprog3 -a world/prog3
# Pairs that checkout into local dir.
prog12 -a prog1 prog2
prog13 -a prog1 prog3
prog23 -a prog2 prog3
# Pairs that checkout into world subdir.
# Instead of using the wprog aliases, we could use "world/prog9"
wprog12 -a wprog1 wprog2
wprog13 -a wprog1 wprog3
wprog23 -a wprog2 wprog3
+1D.12 What does "merge" mean?
A merge is a way of combining changes made in two independent
copies of the same "base" file. There are always three files
involved in a merge: the original, or "base", file and two
copies of that base file modified in different ways.
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>" command merges a whole branch into
your working file, which is presumed to be on the Main line of
development.
See 4C.6
3. The "update -j <rev> -j <rev>" merges the difference between
two specific revisions on some other branch (though the two
revisions are usually on the same branch) into your working
directory.
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 assigned one or more persons to understand,
baby-sit and administer both the CVS programs and the data
Repository. I call these persons Repository Administrators.
They will 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 installation set the RCSBIN directory
to null (""), 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.
[Note: This is not in 1.3 -- It should appear in
the next release.]
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.
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?
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:
add, checkout, commit, diff, log, status, tag, update
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 directory that "checkout" created?
=2B.4 How do I find out what has changed?
=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'll find out that the
module name is named <module>. Then type:
cvs checkout <module>
cd <module>
emacs <file> # Isn't Emacs a synonym for editor?
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 check out a single file, you'll have to change the "cd
<module>" to "cd to the parent of the file named in <module>".
=2B.2 If I edit multiple files, must I type "commit" for each one?
No. You can do them all at once by name or by directory.
See 3D.2.
2B.3 How do I get rid of the directory that "checkout" created?
Change your directory to be the same as when you executed the
"checkout" command and type:
cvs release -d <module>
The current version of CVS does not detect foreign directories
(i.e. ones that weren't created by CVS) in your working
directory and will destroy them.
If you don't care about keeping "history", and you don't care to
plan ahead to a more completely implemented "release" command, you
can just remove it. That's "rm -rf <module>" under Unix.
=2B.4 How do I find out what has changed?
There are many ways to answer this.
To find out what you've changed in your current working directory
since your last 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 display files CVS doesn't know about in
your working directory marked with a '?' indicator.
? <file>
To add <file> to the Repository, type:
cvs add <file>
cvs commit <file>
=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 five possible results when you type
the "update" command:
1. If neither you nor others have made changes to <file>, "update"
will print nothing.
2. If you have made no changes to a file, but others have, CVS
will replace your working file with a copy of the latest
revision of that file in the Repository. You will see:
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.
3. If you have made changes, but others have not, you will see:
M <file>
Nothing happened except you were told that you have a modified
file in your directory.
4. If both you and others have made changes to a file, 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. You will see:
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. This is one of the few times the
otherwise nonsensical phrase "same difference" means something.
5. If both you and others have made changes to the same section of
a file, CVS will merge the changes into your file as in #4
above, but it will leave conflict indicators in the file.
You will see:
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 strange-looking
text marking the overlapping text.
You must examine the overlaps with care and resolve the
problem without removing all previous work.
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, 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 branch might have been abandoned in the past.
6. An explicit revision number. 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.
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.17.
----------------
-- 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 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 sub-directories in my working directory?
Yes, but the "update" command will traverse them, wasting a lot
of time. You can't currently ignore directories but if a
directory has no ./CVS administrative directory, nothing will
happen to it during an "update".
On the other hand "release -d" will delete it without warning.
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:
Add directory /Repos/<dir> to the Repository (y/n) [n] ?
If you type a 'y', you will create both a 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 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
2. Remove the old file using CVS.
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".
cd <working-dir>/<odir>
rm <ofile>
cvs remove <ofile>
cvs commit <ofile>
3. Retrieve <newfile> and remove all the Tags from it.
By stripping off all the old Tags, the "checkout -r" and
"update -r" commands 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 the build system (e.g. Makefile) in
your <working-dir> to know about the name change.
2C.5 How do I make sure that all the files and directories in my
working directory are really in the Repository?
Normally, you only need to be notified of files you forgot to
"add". A simple "update", or "cvs -n update" (which won't modify
your working directory) will display non-added files preceded by a
'?' indicator. To recover, "add" and "commit" them.
To verify that all your directories are in the Repository, you
have to go look. Though CVS traverses all directories, it
produces no output for directories not backed up by a Repository
directory.
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 'M'odified,
'U'pdate and 'C'onflict indicators 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 use the provided template for the "modules" file, both the
CVSROOT and the "modules" module will have the "mkmodules" program
as a "commit helper".
After a file is committed in these modules the "mkmodules"
command will convert all the files CVSROOT directory within 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 all the new files.
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 and commit all three copies of the same file into three
distinct files. This is a hand-editing job, not something
CVS can handle. [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.
Also, as in the "rename" case, you can apply this idea to
directories too, by changing <path> to <pathA>, <pathB> and
<pathC> in the example.
Of course, you have to change your build system (e.g. Makefile).
----------------
-- 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" stuff?
2D.11 Why does .cvsignore not ignore directories?
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" command that will display all system
calls as they happen. This is a *very* low-level interface, but
it can be useful.
The most complete answer is to read the source, compile it
with the '-g' option and execute 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, which 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. (In
the future, "commit" might set a sticky branch tag on a newly
added file.) 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 doesn't pay attention to anything -- it just
registers the desire to add a new file. When a newly added file
is `committed", CVS *should* use the "directory tag" to determine
what branch to commit it to and set the corresponding sticky tag.
Unfortunately, it doesn't work correctly in CVS 1.3. See 4C.8.
=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 virtual branches of development contained in your working
directories. When one of you decides to commit the file, the
other may not commit the same file until "update" has merged the
two together.
Say you both check out rev 1.2 of <file>. 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.
After you resolve any overlaps caused by the merging process, you
may then commit the file.
Yes, the first one who commits can cause the other some work.
Yes, between the time you execute "update" and "commit", someone
else may have committed a later 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.
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 who
has what 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, #4
and #5 will be the same. But you might then make 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
rat's nest 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.
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" stuff?
The "update" and "import" commands use collections of Unix
wildcards to skip over files matching any of those patterns.
You may add to the built-in ignore list by adding 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 in the X tree 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 files without known suffix patterns.
In any of the 5 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.
2D.11 Why does .cvsignore not ignore directories?
Ignore lists are intended to be per-directory wildcards matching
various patterns. They are matched against file names, not
directory names or relative paths ('/' is an invalid character in
an ignore list). I suppose it could be extended, but as it
stands, it only works on files.
This might change in the future.
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 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.
First, you 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 applying a raw "rcs -n" to
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.
Halting "update" half-way will give you some strange collection
of files and revisions. You'll have to examine the output from
the command and take a look at each file that was modified. 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 is a script called "cvs_acls.pl" that implements
a form of access control.
========================================
== 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 newly added file end up in the Attic?
3A.4 How do I put a new file on the Main Branch and branch off from
there onto my default branch?
**** 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, after verification, 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?
See 4C.8
3A.3 Why did my newly added file end up in the Attic?
Your new file is placed in the Attic if it is added onto a side
branch without ever showing up on the trunk.
If the file were in the main Repository area, it would show up
when the Main branch is checked out. You didn't commit it onto
the Main branch -- only onto the side branch.
3A.4 How do I put a new file on the Main Branch and branch off from
there onto my default branch?
See 4C.8
----------------
-- 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
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 also use the '-o' (for "outdate") option to remove
revisions you don't care about. This has its own problems, such
as leaving dangling Tags and confusing the "update" command.
=3B.4 What should I avoid when using "admin"?
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.
Don't try to use the '-l' option, which will lock RCS files.
See 4D.7 for a cautionary scenario.
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 on checkout 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" 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" 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 ./CVS administrative directory.
4. The two commands generate completely different types of records
in the "history" file.
The two commands are equivalent in nearly all other respects.
3C.5 Why can't I check out a file from within my working directory?
You normally check out a module or directory, not a file. 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 names for both 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 "module".
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.
I consider it unfortunate that CVS sprouted the ability to check
out relative pathnames without more extensive and flexible
support for "modules."
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 on checkout the way RCS does?
Think about why you want that ability. RCS locking is there to
keep people from breaking individual files. CVS does the same
task a different way. If you are only looking for the consistency
aspect, then you should just forget about locking. For normal
development, there is no need for CVS to lock anything.
If you want to restrict access to parts of the Repository, see
the question in Section 4B on "Limiting Access".
+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).
[[CVS 1.3 fails to handle all the flags you can put into the
modules file. The '-l' switch in particular causes "checkout -c"
to dump core on some systems.]]
----------------
-- 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 <branch_tag>" put new files in the attic?
+3D.8 Why does "commit -r <rev>" ignore <rev> on an added file?
**** 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 on the
command line and commit them all with the same log message.
If the file is unchanged, 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 second checkin of minor changes from 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 simultaneous 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 for being
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 remembers any "-r <tag/rev>" arguments handed to the
"checkout" or "update" commands. This is the "sticky" part. 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 {optional files, default is whole directory}
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, 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:
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 details.
=3D.7 Why does "commit -r <branch_tag>" put new files in the attic?
This was a design choice. The Attic is a way to keep track of
files that are no longer on the Main Branch, or ones that were
*never* on the Main Branch.
If the file doesn't already exist on the Main branch, committing
it directly to the BRANCH will stuff it into the Attic. Such
files are skipped over when checking out the Main Branch because
the file isn't on that branch.
If it didn't go into the Attic, you would be committing the new
file to the Main branch in addition to the Branch you are working
on. This is an undesirable side-effect.
The file can be retrieved by using the "-r <branch_tag>" option on
a "checkout" or "update" command.
See Section 4C, on Branching, for many more details.
+3D.8 Why does "commit -r <rev>" ignore <rev> on an added file?
The sequence
cvs add <file>
cvs commit -r <rev> <file>
does not commit the new file <file> with revision <rev> as you
might expect. For newly added files (for which "update" would
display an 'A') the '-r' option is assumed to be a branch tag. If
<rev> is numeric, it is ignored. This might or might not be
changed in future revisions of CVS, but for now, the following
commands will allow you to set the revision of the file: (with
some restrictions)
cvs add <file>
cvs commit <file>
cvs commit -r <rev> <file>
The first commit causes CVS to look for the highest main branch
major number in all files in the directory. 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.
As long as <rev> is higher than the initial (calculated as in the
above) revision, the second commit will work as expected and force
a second commit even if the file hasn't changed, setting the file
revision to <rev>.
----------------
-- 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 the --unified option to "diff"?
**** Answers:
3E.1 What is "diff" for?
To display the difference between your working file and a
committed revision:
cvs diff -r <tag/rev> <file>
or between two committed revisions:
cvs diff -r <tag1/rev1> -r <tag2/rev2> <file>
Without explicit file names, it "diffs" the whole directory.
Without explicit revision numbers, it "diffs" your working file
against the BASE revision, which is the one last checked out,
updated or committed.
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 the --unified option to "diff"?
There are a few reasons:
1. CVS passes through only arguments it knows about, because a few
arguments are captured and interpreted.
2. CVS only parses single character '-X' arguments, not the FSF
long options.
3. 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 the hell not?
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 in CVS 1.3. Maybe later.
=3F.4 Why the hell not?
Export is intended for a specific purpose -- to remove all trace
of revision control on the way *out* of CVS. Maybe in the future
CVS will allow the -kv default to be overridden.
3F.5 Why does "export -D" check out every file in the Attic?
See the explanation of the same problem with "update -D"
contained in section 5B.
----------------
-- 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?
**** 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?
In later versions of CVS, you can use the '-f' option which
forcibly adds a "release" record to the history file. If your
version of "release" doesn't have the '-f' option, 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".
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
----------------
-- 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 you put it on
the Main Trunk and let me work on a 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 keep "import" from expanding all the $\Revision$ strings
to be 1.1.1.1?
#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 didn't "import" ignore the directories I told it to?
3H.10 Why can't I "import" 3 releases on different branches?
3H.11 What do I do if the Vendor adds or deletes files between releases?
3H.12 What about if the Vendor changes the names of files or
directories, or rearranges the whole structure between releases?
3H.13 I thought "import" was for Vendor releases, why would I use it
for code of my own? Do I have to use import?
=3H.14 How do I import a large Vendor release?
+3H.15 Explain: ERROR: cannot create link to <file>: Permission denied
**** 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.
"cd" into your source directory and type:
cvs import -m "Message" <repos> <Vendor-Tag> <Release-Tag>
where <repos> is a relative directory pathname within the
Repository.
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.14 for more details.
=3H.3 Why does import put files on a branch? Why can't you put it on
the Main Trunk and let me work on a branch?
Design choice. If you don't like the Vendor branch, you can use
the RCS "ci" command to generate all the RCS (",v") files and move
them into the Repository directly.
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.
3H.4 Is there any way to import binary files?
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>
See 4D.1 on Binary files.
3H.6 How do I keep "import" from expanding all the $\Revision$ strings
to be 1.1.1.1?
If you want to leave old RCS keywords as they are, you can use the
'-ko' trick described above. In the future, "import" might
sprout a '-ko' option of its own, so you don't have to execute two
commands.
#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 {} ';')
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?
In the released CVS 1.3, there is no way. In the coming patch
release, there will supposedly be a '-d' option to save the dates
of the files rather than the current date.
See 4D.8 for more details.
3H.9 Why didn't "import" ignore the directories I told it to?
See 2D.11.
3H.10 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.11 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 "remove" (followed by "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]".
3H.12 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.9 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.13 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. It is not necessary. You can just as easily
checkin all the files using the RCS "ci" command and move the
resulting ",v" files into the Repository.
See Section 4B, on Setting up and Managing the Repository.
=3H.14 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.
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.
4. If they renamed any files, see 4B.9 on renaming files.
5. When you have dealt with removed and renamed files, then you
can execute the import:
cd <new source>
cvs import -m "Message" <repos> <VendorTag> <ReleaseTag>
Where
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 '-'.)
6. *SAVE* the output from the import command.
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. Alternatively, you can examine every file in the
"find" at the beginning and use the "import -I !"
option to avoid ignoring anything.
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.
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>
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.
+3H.15 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.
----------------
-- 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 (what RCS calls "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:
cvs log -r<rev1>:<rev2> <file>
If either <rev1> or <rev2> contain '-' characters, it will
complain and fail due to RCS's continued support of '-' as an
alternate range character.
<rev1> and <rev2> can be tag/symbol names, but they have to be
on the same branch, whether they are numeric or symbolic.
=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.
3I.4 How do I generate ChangeLogs from RCS logs?
A program called rcs2log is distributed as part of GNU Emacs 19.
This program should also appear in the CVS FTP archive.
=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 the version of "diff" you are using supports the '-u' option,
to produce the more compact "Unidiff" format, the latest
revisions of the patch command understand that too.
----------------
-- Section 3K -- "release", "re", "rel"
----------------
**** Questions:
3K.1 What is "release" for?
3K.2 Why does release -d delete directories within my directory that
weren't ever in the CVS Repository?
3K.3 Why can't I reverse a "cvs checkout path/name/subdir" with a
"cvs release path/name/subdir" without an "unknown module name"?
3K.4 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.5 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.6 Why doesn't "release -d module" reverse a "checkout module"?
3K.7 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 does release -d delete directories within my directory that
weren't ever in the CVS Repository?
A simplistic implementation. (I can say this -- I wrote it.)
The "release" function was written under the assumptions that the
"module name" is a first class, unavoidable interface to the
Repository, allowing no way to retrieve anything other than by
module name and a module is a self-contained entity with no
foreign directories allowed. 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 those
assumptions. It will be upgraded slightly in the next release and
rewritten in the future.
3K.3 Why can't I reverse a "cvs checkout path/name/subdir" with a
"cvs release path/name/subdir" without an "unknown module name"?
Again, "release" is too primitive. It believes, truly
*believes* in modules, not relative paths. I can't *believe*
how many times I've been asked this. It was a hack of the
moment with a particular use in mind. I had no idea it was
going to cause so much trouble. I'll *fix* it already! :-)
3K.4 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.
Again, "release" believes in modules. Breaking it into bits
wasn't part of the plan. In the future, "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.5 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.6 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.7 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:
cvs remove: no files removed; use `rm' to remove the file first
**** 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:
cvs remove: no files removed; use `rm' to remove the file first
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.
Future versions of CVS might contain a '-f' switch that deletes
the existing file without complaining.
----------------
-- Section 3M -- "rtag", "rt", "rfreeze"
----------------
(See the "tag" section below for questions in common with "rtag".)
**** Questions:
3M.1 What is "rtag" for?
3M.2 Why would you use "rtag"? It assumes a static Repository.
**** 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 would you use "rtag"? It assumes a static 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.
----------------
-- 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 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 Shouldn't the status "Needs Checkout" be "Needs Update"?
Probably. Maybe in future revisions.
----------------
-- 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 "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 copy of my current files?
#3O.8 Why doesn't "tag" write a history record the way "rtag" does?
**** 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 particular revision 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.
"tag" works on files and directories in the current working
directory.
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.
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?
Design decision. 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. See 4C.3 on Creating a Branch.
-3O.4 So "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 copy 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 more useful than "rtag", so the model
has changed. Future revisions of CVS will probably store both
kinds of tags in the history file.
----------------
-- 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 After a merge ("update" or "update -j"), why doesn't CVS remember
the conflict and not allow you to commit the result until the
conflict is resolved?
3P.7 Is there a feature to tell me what I have changed, added and
removed without changing anything?
=3P.8 Why does "cvs update" not flag directories that are not in the
Repository as it does with new files?
3P.9 Why are all my files deleted when I execute "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 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 by
other people into your working files, type:
cvs update {optional list of files}
3. To merge changes made to 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/rev1> -j <tag2/rev2> {optional files}
(If you are working with a single file, the Tags could also be
revisions numbers. Unless you take really unusual care to
match revision numbers across different files (a waste of time
given the way Tags work), using revision numbers in places 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}
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.
You will need to remove the conflicts by editing the file.
Conflicts are surrounded by <<<<< and >>>>> markers.
"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 and 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".
And now your disk caches are furiously being flushed by
multiple update daemons, destroying performance and proving to
management that you need more CPU power. :-)
6. Someone backed out 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 the
revision CVS thinks you already have. 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 the
normal cycle of "emacs" (a synonym for "edit" in most of the
civilized world) and "commit".
=3P.6 After a merge ("update" or "update -j"), why doesn't CVS remember
the conflict and not allow you to commit the result until the
conflict is resolved?
Maybe in a future release. There is a "sticky_conflict" patch you
might want to look at in the CVS FTP archive.
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 does "cvs update" not flag directories that are not in the
Repository as it does with new files?
Design choice or oversight, take your pick. Directories are
handled specially. You can aim "update" at any random directory
and "update" will traverse the whole directory tree beneath it,
looking for CVS administrative directories. When it finds one,
"update" will perform its "normal" function.
Maybe a future release will notice a directory not under CVS,
print a '?' and skip over it.
3P.9 Why are all my files deleted when I execute "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 files 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 4D.14.
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.3 for
suggestions.
4. Make sure you have versions of all the programs mentioned in
the "cvs/src/config.h" file.
5. 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 Makefiles and "cvsinit" program.
2. Edit the "config.h" file in the "src" directory.
Read it carefully.
You will need to specify a number of site-specific pieces of
information including the names of a number of functions.
Hint1: You really 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.5 or greater and set the
"HAVE_RCS5" macro.
3. Execute the ./configure command.
4. Type "make".
=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.)
2. Make sure you have versions of all the programs mentioned in
the config.h file, most of which are included in a standard
Unix system.
3. Unless you plan to reimplement RCS [:-)], you must install RCS.
4. 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 4D.11.
----------------
-- 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 How do I manage the modules file?
4B.8 Why would anyone use "modules"? They are too restrictive. I
want to be able to select just the files I want to edit.
=4B.9 How do I rename a file or directory? What are the consequences?
=4B.10 What are "Attic" directories?
4B.11 Is it OK to remove anything from the Repository?
4B.12 Can I convert to CVS from RCS without losing my revision history?
=4B.13 Can I move RCS files with branches in them into the Repository?
=4B.14 Can I use raw RCS commands on the Repository?
4B.15 How do I convert from SCCS to RCS?
=4B.16 How do I limit access to the Repository?
=4B.17 What are the Repository Administrator's responsibilities?
4B.18 How do I move the whole Repository?
+4B.19 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". Execute:
cvs checkout CVSROOT
and read the information stored in 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, in order 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 seven Repository control (or "database") files of
interest in the CVSROOT directory:
1. 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.
2. 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.
3. 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.
4. 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.
5. cvsignore contains "ignore" patterns that are added to the
built-in ignore list. See 2D.10.
6. 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.
7. modules contains the "modules" database. See 1D.11, 2C.7,
4B.7 and 4B.8 for more details.
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,
one at a time.
3. You can move RCS files directly into the Repository.
It would probably be a good idea to create directories to hold
them.
=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. It 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.)
- 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.
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
[[Future versions of CVS might sprout a "umask" configuration
variable.]]
=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 different
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 How do I manage the modules file?
An equivalent question might be, "How do I structure my sources?"
This can be a difficult question in that it is not purely
technical.
Generally you want to think about what pieces of your system need
to be checked out together, built as one system or tagged
consistently. You should certainly make 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 containing files that will usually
be worked on at the same time by the same person.
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.
4B.8 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.9 How do I rename a file or directory? What are the consequences?
In CVS 1.3 there is no single CVS "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, "remove"
the old file and "add" the new one. Since there is no way (in
CVS 1.3) 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.10 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.11 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 Outer Space.
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.12 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.13 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.14 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.15 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.16 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. You can:
1. Set Unix groups and permissions. See 4B.5.
2. Try the "setgid" trick described in 4D.16.
3. Catch every commit using the "commitinfo" file.
4. Try to use the RCS access control lists, though I don't
think CVS will handle them cleanly.
5. Edit the source code to CVS.
=4B.17 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, everything in the Repository
should be "under" CVS.
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. Maintaining the other Repository control files: commitinfo,
loginfo, rcsinfo and editinfo files.
4. Storing site-specific ignore patterns in the "cvsignore" file.
5. Pruning the history file every once in a while. (Try the
"cln_hist.pl" script in the "contrib" directory.)
6. Staying aware of developments on the info-cvs mailing list and
what is available in the FTP archive.
7. Run "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.
8. 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.18 How do I move the whole Repository?
The Repository itself contains pathnames only within the files in
the CVSROOT directory. If helper functions in the modules file or
logging programs executed out of the loginfo file point into the
Repository, you'll have to change the pathnames to point to the
new Repository location.
The main change you'll have to make is to all the ./CVS/Repository
files in the checked-out working directories.
You have four choices:
1. If you can avoid changing $CVSROOT by using a symbolic link or
mount point you don't have to do anything else.
If you must change $CVSROOT, you must also tell everyone to
change the CVSROOT environment variable in all running shells
and in their '.' files where it is set. Then pick one of the
other three options that follow:
2. If all ./CVS/Repository files in all working directories
contain relative pathnames, you don't have to do anything else.
3. 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.
4. Use a PERL or shell script to run through all the
./CVS/Repository files and edit the values in the files.
+4B.19 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 other than by changing the Repository file
directly.
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
----------------
**** 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 add a new file to a branch?
=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 Why do I get the latest files on the branch when I tried to
"update -r <tag>"?
**** 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 "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 should create a branch are when:
1. You expect to take a long enough time or make a large enough
set of changes that the merging process will be difficult.
2. 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. 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. 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 short form:
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 move your working directory to the branch.
Suggested short form using modules:
A1. cvs rtag <branch_point_tag> module
A2. cvs rtag -b -r <branch_point_tag> <branch_tag> module
A3. cvs checkout -r <branch_tag> module
Suggested short form using your working directory, which contains
the revisions of your working files you want to branch from:
B1. cvs tag <branch_point_tag>
B2. cvs rtag -b -r <branch_point_tag> <branch_tag> module
B3. cvs update -r <branch_tag>
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).
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 files and the result is the
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 B2 has two important 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. If you have trouble figuring out what "module" to use,
remember that "module" can also mean "relative path within
the Repository." If that doesn't help, you can aim it at
whatever parent directories you believe will cover all
your files. 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.
Step 3 may occur any time after step 2. Unless you explicitly
remove them with "tag -d", the Tags are permanent.
There are two obvious ways of to choose the <branch_point_tag> and
<branch_tag> names. Since 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 what ever 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:
- The "-r <tag>" option 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 precise.
Check out or "update" the files you want to merge into.
Identify the two tags on the branch you want to merge from.
(Revisions don't work too well because the same revision doesn't
mean the same thing in different files.) Then type:
cvs update -j <tag1> -j <tag2>
You can use a <branch_tag> to refer to the latest revision on the
branch, but there is no built-in way to refer to the branch point.
An alternative to merging is to identify a single revision you
want, grab it by using "update -p" and commit it. If you do
merges later, you'll get overlaps, but you get your file.
In the future, (but not yet) merging from the main branch will
look something like this:
cvs update -j MAIN
cvs commit -m "Log message"
4C.8 How do I add a new file to a branch?
The obvious technique is broken in CVS 1.3. This is the way it is
supposed to work:
You are in a directory checked out (or updated) with the "-r
<branch_tag>" option. To add <file> to the branch named
<branch_tag> you type:
cvs add <file>
cvs commit <file>
Until the next release appears, you must explicitly specify the
branch_tag:
cvs add <file>
cvs commit -r <branch_tag> <file>
One not so obvious side-effect is that the file ends up in the
Attic. It wasn't added to the Main Branch so it doesn't show up
in the main part of the Repository, only in the Attic.
You can add it to the Main Branch and branch off from there onto
the side-branch this way:
1. Move the working file back to the main branch:
cvs update -A <file>
2. Add the file "normally":
cvs add <file>
cvs commit <file>
3. Branch-tag the file using the same <branch_tag> as you did on
all the other files in your directory:
cvs tag -b <branch_tag> <file>
4. And move the file back onto the branch:
cvs update -r <branch_tag> <file>
=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 should be added to the Tag stored
in ./CVS/Tag, but they are not. See the above question on adding
a new file to a branch.
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 there aren't 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 $CVSROOT/CVSROOT.
You tell "checkout" or "update", via the "-r <tag>" option,
what branch you want to check out. 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 make a "merge" 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.
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 "cvs checkout -j <branch_tag> <module>".
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-magic 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* holds all the changes on the branch.
*2* cvs diff -r <branch_point_tag> -r HEAD
>>> *2* holds 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
and overlaps.
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.
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 the
Vendor branch. Think about it. How does revision
1.2.4.2.4.2.2.1 grab you?)
+4C.17 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 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.
You *can* branch off a branch, but it is rarely needed.
----------------
-- 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 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 Why does the merge occasionally resurrect lines of code?
=4D.11 Why does the merge fail when my "rcsmerge" program is
configured to use GNU diff version 2.1 or later?
4D.12 What the hell is Entries.Static?
=4D.13 Why did I get the wrong Repository in the loginfo message?
=4D.14 Can I have multiple source repositories, one for each project?
4D.15 How do I run CVS setuid so I can only allow access through the
CVS program itself?
4D.16 How about using groups and setgid() then?
4D.17 How do I use the "commitinfo" file?
4D.18 How do I use the "loginfo" files?
**** 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 also need to apply the '-ko' flag to the files to avoid
expanding RCS keywords, which can be done via:
cvs admin -ko filename
(You should be able to do it by handing "import" the -ko option,
but that isn't yet in the official release.)
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.
[[I know of no solution to this other than to keep binaries in
some text form as "source" (real binaries could be uuencoded,
documents could be stored in "exported" (something like SGML)
form.]]
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 had never realized how much help CVS/RCS 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 filename, by typing:
cvs admin -N<tag> <file>
2. Retrieve the outdated revision.
Using CVS and RCS, there is no way to reconstruct an outdated
revision. You will have to resort to backups.
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 a magic branch tag?
If the <branch_tag> refers to a physical branch within an RCS
file, renaming a tag will make the existing branch in the file
seem to disappear. This is not a good idea.
If the magic branch has never had a revision committed to it, you
can move the branch by re-executing the "tag" or "rtag" command
that created it. The <branch_tag> will be moved to the place
where it would have appeared if you were tagging the file for the
first time.
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 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.
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.
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.
=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: I commit a source file at 5PM. You commit the same file
at 6PM. At 7PM, I compile my file. Then I execute "update". If
CVS sets the date to the one in the RCS file, the file would be
given a timestamp of 6PM and my 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.
#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 given the promise offered by '-n' not to alter
anything. The "diff", "log" and "stat" commands all provide the
same information 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 this is "cvs -n <command>". The visually similar
command "cvs <command> -n" has no relation to the former 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 entirely reliably.
4D.10 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.
If you plan to upgrade to the latest GNU diff program, see the
next question.
=4D.11 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.
To get consistent rcsmerge behavior, you have four choices:
1. Go back to using GNU diff 1.15 or 2.0. 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.
4D.12 What the hell is Entries.Static?
Each ./CVS administrative directory contains an Entries file,
listing the files under CVS in the directory above it. If a new
file is added to the Repository, an "update" command copies it
out of the Repository and adds it to the Entries file.
If your ./CVS directory has an Entries.Static file in it, CVS
checks it before bringing new files out of the Repository. If a
new file is *not* in Entries.Static, it is not checked out.
The Entries.Static file is created by checking out something that
doesn't include all files in a directory. Without an
Entries.Static file, the first "update" would bring more files
out of the Repository.
Examples:
- A multi-module checkout renamed with the "checkout -d" option.
- Checking out a module specified with directory and filenames.
The Entries.Static file is removed by an "update" with the
'-A', '-r' or '-D' option.
=4D.13 Why did I get the wrong Repository in the loginfo message?
You probably:
- Use multiple Repositories.
- Configured CVS to use absolute pathnames in the
./CVS/Repository file.
- Typed the "commit" command in one Repository with your
$CVSROOT pointing at the other.
"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.
=4D.14 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.
One monster of an unexpected result can happen when you have
two modules or directories by the same name at the same
relative path inside the Repository, in two different
Repositories. You can 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.
4D.15 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.16 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", for example. Name it as you wish.
2. Put *no* users in the "cvsg" group. You can put Repository
administrators in this group, if you really 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 {} \;
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 allow the world
execute bit (octal 001) on directories, 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 the "admin" problem with the
setuid() method.
4D.17 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 the function 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.
- 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.
- 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 as many times as you like.
4D.18 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") 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
----------------
-- Section 4E -- Weirdness
----------------
**** 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 I don't want a Vendor branch. Why can't I work on the main trunk?
4E.4 Merges can't work. I don't trust them. If you won't change it to
something I can understand, I won't use CVS.
4E.5 Explain: "co error, line 2: Missing access list"
+4E.6 Explain: "error: RCS file name `xyz .c' contains white space"
+4E.7 Explain: cvs checkout: warning: <X> is not (any longer) pertinent
**** 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.
=4E.3 I don't want a Vendor branch. Why can't I work on the main trunk?
The Vendor branch is the way "import" deals with a Vendor
release. If you do it any other way, you are wasting your time.
CVS was designed to work this way.
If you are not working with 3rd party (i.e. Vendor) sources, you
can skip the "import" and either move pre-existing RCS files into
the Repository, or apply the RCS "ci" command to your source files
by hand (creating ",v" files) and move them into the Repository.
4E.4 Merges can't work. I don't trust them. If you won't change it to
something I can understand, I won't use CVS.
Some developers have the feeling that three-way merging doesn't
work. They don't trust 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 obliterate.
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.
4E.5 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.
You should upgrade to the latest version of RCS, which is Version
5.6.0.1 as I write this.
+4E.6 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.7 Explain: cvs checkout: warning: <X> is not (any longer) pertinent
This message occurs in two 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.
----------------
-- 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 1.3 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'),
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 is a window interface to CVS written in Tcl/Tk, which attempts
to hide the normal CVS command line options from novice users.
GIC works only in a single directory at a time, but it offers most
of the CVS commands you would normally use.
GIC can be obtained by anonymous ftp to
ftp.cpsc.ucalgary.ca:/pub/marwood/gic-1.0b5.tar.Z
contact
David Marwood
marwood@cpsc.ucalgary.ca
[[Does someone want to try to describe this better?]]
+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 llnl.gov [128.115.18.253] as
gnu/caveman_vX.Y.Z.tar.gz (The numbers X, Y, & Z vary with time.)
contact
Kathleen Dyer kdyer@llnl.gov
(510)423-6803
(510)423-5112 FAX
[[Does someone want to try to describe this better?]]
----------------
-- Section 4G -- Other Systems
----------------
**** Questions:
4G.1 I use a NeXT. Is there anything I need to know?
4G.2 I use OS/2. Is there anything I need to know?
4G.3 I use SCO Unix. Is there anything I need to know?
4G.4 I use AIX. Is there anything I need to know?
=4G.5 I use IRIX. Is there anything I need to know?
=4G.6 I use an HP system. 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.
4G.1 I use a NeXT. Is there anything I need to know?
Under NeXTSTEP 2.2, the tmpnam() function always returns the
same filename, which breaks "cvs patch". Apparently the
"mktemp()" function works OK, but you'll have to hack it up to
build something that acts like "tmpnam()".
NeXTSTEP 3.0's Interface Builder uses "nib" directories,
rather than files 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.
[[Anything else?]]
4G.2 I use OS/2. Is there anything I need to know?
[[Well?]]
4G.3 I use SCO Unix. Is there anything I need to know?
[[Well?]]
4G.4 I use AIX. Is there anything I need to know?
[[Well?]]
=4G.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.
=4G.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.16, 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
=============================================
== 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.
Take a look at the README and the ChangeLog files in the CVS
sources for more details.
=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. 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.
Unless a name is included in the answer itself, I didn't use
anyone else's answers verbatim. On the other hand, I did use
ideas and information provided by many. 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):
Donald Amby <amby@mixcom.mixcom.com>
Tom Cunningham <tomc@bouwsma,sps.mot.com>
Don Dwiggins <dwig@markv.com>
Dan Franklin <dan@diamond.bbn.com>
Jeffrey M Loomis <jml@world.std.com>
Barry Margolin <barmar@think.com>
Mark K. Mellis <mkm@ncd.com>
Chris Moore <Chris.Moore@src.bae.co.uk>
Gary Oberbrunner <garyo@think.com>
Steve Turner <stevet@carrier.sps.mot.com>
Dave Wolfe <dwolfe@pffft.sps.mot.com>
Dale Woolridge <dwoolridge@cid.aes.doe.ca>
Plus a myriad Thinking Machines people who posed hundreds of
questions.
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 Why does "checkout" recurse indefinitely if an alias contains
its own name?
5B.4 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.5 When I typed "cvs update -D <date>" in my branch, why did it
screw up all my files?
5B.6 When I executed "checkout" into an existing directory I got "No
such file or directory" errors. Why?
5B.7 Why does "update" send all output to the terminal after 26 files
have been updated?
+5B.8 Why doesn't the "-I !" option work in update and import?
**** 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.9 and 2C.4.
=5B.3 Why does "checkout" recurse indefinitely if an alias contains
its own name?
A bug in the handling of aliases. [[I'll remove this one when
the bug is fixed.]]
5B.4 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.
5B.5 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.
5B.6 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.7 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.8 Why doesn't the "-I !" option work in update and import?
A bug. See the patch named "unoff/import_ignore" in the CVS FTP
archive
[[Section 5B needs more, but should probably wait until the
patch release comes out. Then we can document them for real and
provide pointers to patches in the FTP area.]]
----------------
-- Section 5C -- Development
----------------
I hope to record three types of information here:
1. Plans (with the developer's name attached) for fixing larger
bugs. (Smaller bugs should just show up, with a patch or a
reference to a patch stored in the FTP archive, in the
"Bugs" section above.)
2. Plans for new development, with the developer's name attached.
(If the developer is particularly gonzo, it might also show a
completion date.)
3. Requests for ideas and code to fix unresolved issues.
**** 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 fixing bugs?
=5C.5 What plans are there for new features?
=5C.6 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.
If careful testing reveals an RCS bug rather than a CVS bug, you
can sendbug reports to: rcs-bugs@cs.purdue.edu
=5C.2 Where do I send fixes and patches?
First make sure the "fix" does something useful. Have someone to
review your fix. It is better to spend a bit of one person's
thinking time than to waste the time of thousands of people trying
to understand your fix.
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, send it to the maintainer of the
FTP archive (currently the author of this FAQ) for inclusion in
the CVS FTP archive and to Brian Berliner, the maintainer of CVS.
5C.3 Where do I send ideas for future development?
[[Brian?]]
5C.4 What plans are there for fixing bugs?
David G. Grubbs <dgg@think.com> plans/hopes to:
- Fix the release command to be more sophisticated about
foreign directories, renaming and to allow the release of
anything in the working directory.
- Fix the history command to track changes made in the
underlying layers since I originally wrote it, including
making "tag" work with history.
[[Brian?]]
[[Others?]]
=5C.5 What plans are there for new features?
David G. Grubbs <dgg@think.com> plans/hopes to:
- Implement the design described in the Branching spec
distributed to this list in January, 93. It attempts to
address the problem of merging between arbitrary branches
and to fully support the idea of "branching".
- Add a feature to "cvs add" (Maybe a '-a' switch.) to
add a file by the same name as one in the Attic, by
dragging it back out of the Attic. (This connects to the
branching code, since a way has to be added to drag a
file out of the Attic that is merged onto the Main branch
from being only on a side-branch.)
- If no one else wants to deal with it, I would like to
enhance the whole "modules" concept to cover more of
the naming problem and to allow more complicated access
control. (Optional, of course.)
- Create a set of configuration files (in addition to or to
supersede the cvsignore files) to allow the setting of
a wide variety of site-specific options.
Brian Berliner <berliner@sun.com> plans/hopes to:
- [[Rename database?]]
[[Brian? Any plans?]]
Paul F. Kunz <pfkeb@slac.stanford.edu> has produced a version of
CVS (RCVS) that runs remotely.
On the host "ftp.slac.stanford.edu", you can find:
Sources: pub/sources/rcvs-0.5.0.tar.Z
Paper: pub/preprints/slac-pub-5923.ps
[[Others?]]
=5C.6 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 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
D. Tricks of the Trade
E. Weirdness
F. Related Software
G. Other Systems
5. Past & Future
A. Contributors.
B. Bugs and Patches
C. Development
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?
=1A.6 Why isn't it called OSCO (Online Source COntrol)?
----------------
-- 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 a copy of the latest version of CVS?
1B.4 Is there any other documentation? How about tutorials?
1B.5 Is there a mailing list devoted to CVS? How do I get on it?
1B.6 What prayers are appropriate for each of the major denominations
(e.g. 20's, 50's, 100's) when issuing complex CVS commands?
+1B.7 How do I get files out of the archive if I don't have FTP?
----------------
-- 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?
1C.5 How does CVS differ from SunPro?
1C.6 How does CVS differ from Aegis?
1C.7 How does CVS differ from Shapetools?
+1C.8 How does CVS differ from TeamNet?
+1C.9 How does CVS differ from ProFrame?
+1C.10 How does CVS differ from CaseWare/CM?
+1C.11 How does CVS differ from Sublime?
----------------
-- 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 directory that "checkout" created?
=2B.4 How do I find out what has changed?
=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 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" stuff?
2D.11 Why does .cvsignore not ignore directories?
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 newly added file end up in the Attic?
3A.4 How do I put a new file on the Main Branch and branch off from
there onto my default branch?
----------------
-- 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 on checkout 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 <branch_tag>" put new files in the attic?
+3D.8 Why does "commit -r <rev>" ignore <rev> on an added file?
----------------
-- 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 the --unified option 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 the hell not?
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?
----------------
-- 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 you put it on
the Main Trunk and let me work on a 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 keep "import" from expanding all the $\Revision$ strings
to be 1.1.1.1?
#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 didn't "import" ignore the directories I told it to?
3H.10 Why can't I "import" 3 releases on different branches?
3H.11 What do I do if the Vendor adds or deletes files between releases?
3H.12 What about if the Vendor changes the names of files or
directories, or rearranges the whole structure between releases?
3H.13 I thought "import" was for Vendor releases, why would I use it
for code of my own? Do I have to use import?
=3H.14 How do I import a large Vendor release?
+3H.15 Explain: ERROR: cannot create link to <file>: Permission denied
----------------
-- 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 does release -d delete directories within my directory that
weren't ever in the CVS Repository?
3K.3 Why can't I reverse a "cvs checkout path/name/subdir" with a
"cvs release path/name/subdir" without an "unknown module name"?
3K.4 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.5 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.6 Why doesn't "release -d module" reverse a "checkout module"?
3K.7 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:
cvs remove: no files removed; use `rm' to remove the file first
----------------
-- Section 3M -- "rtag", "rt", "rfreeze"
----------------
3M.1 What is "rtag" for?
3M.2 Why would you use "rtag"? It assumes a static Repository.
----------------
-- 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 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 "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 copy of my current files?
#3O.8 Why doesn't "tag" write a history record the way "rtag" does?
----------------
-- 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 After a merge ("update" or "update -j"), why doesn't CVS remember
the conflict and not allow you to commit the result until the
conflict is resolved?
3P.7 Is there a feature to tell me what I have changed, added and
removed without changing anything?
=3P.8 Why does "cvs update" not flag directories that are not in the
Repository as it does with new files?
3P.9 Why are all my files deleted when I execute "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 get around the bugs I've heard of GNU diff version 2.2?
----------------
-- 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 How do I manage the modules file?
4B.8 Why would anyone use "modules"? They are too restrictive. I
want to be able to select just the files I want to edit.
=4B.9 How do I rename a file or directory? What are the consequences?
=4B.10 What are "Attic" directories?
4B.11 Is it OK to remove anything from the Repository?
4B.12 Can I convert to CVS from RCS without losing my revision history?
=4B.13 Can I move RCS files with branches in them into the Repository?
=4B.14 Can I use raw RCS commands on the Repository?
4B.15 How do I convert from SCCS to RCS?
=4B.16 How do I limit access to the Repository?
=4B.17 What are the Repository Administrator's responsibilities?
4B.18 How do I move the whole Repository?
+4B.19 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
----------------
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 add a new file to a branch?
=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 Why do I get the latest files on the branch when I tried to
"update -r <tag>"?
----------------
-- 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 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 Why does the merge occasionally resurrect lines of code?
4D.11 Why does the merge fail when my "rcsmerge" program is
configured to use GNU diff version 2.1 or later?
4D.12 What the hell is Entries.Static?
=4D.13 Why did I get the wrong Repository in the loginfo message?
=4D.14 Can I have multiple source repositories, one for each project?
4D.15 How do I run CVS setuid so I can only allow access through the
CVS program itself?
4D.16 How about using groups and setgid() then?
4D.17 How do I use the "commitinfo" file?
4D.18 How do I use the "loginfo" files?
----------------
-- Section 4E -- Weirdness
----------------
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 I don't want a Vendor branch. Why can't I work on the main trunk?
4E.4 Merges can't work. I don't trust them. If you won't change it to
something I can understand, I won't use CVS.
4E.5 Explain: "co error, line 2: Missing access list"
+4E.6 Explain: "error: RCS file name `xyz .c' contains white space"
+4E.7 Explain: cvs checkout: warning: <X> is not (any longer) pertinent
----------------
-- Section 4G -- Other Systems
----------------
4G.1 I use a NeXT. Is there anything I need to know?
4G.2 I use OS/2. Is there anything I need to know?
4G.3 I use SCO Unix. Is there anything I need to know?
4G.4 I use AIX. Is there anything I need to know?
=4G.5 I use IRIX. Is there anything I need to know?
4G.6 I use an HP system. 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 Why does "checkout" recurse indefinitely if an alias contains
its own name?
5B.4 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.5 When I typed "cvs update -D <date>" in my branch, why did it
screw up all my files?
5B.6 When I executed "checkout" into an existing directory I got "No
such file or directory" errors. Why?
5B.7 Why does "update" send all output to the terminal after 26 files
have been updated?
+5B.8 Why doesn't the "-I !" option work in update and import?
----------------
-- 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 fixing bugs?
=5C.5 What plans are there for new features?
=5C.6 I have some time and I'd like to help. What can I do for you?
=================================================
== 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:
Reference in New Issue View Git Blame Copy Permalink