7739 lines
250 KiB
Plaintext
7739 lines
250 KiB
Plaintext
|
\input texinfo @c -*-texinfo-*-
|
|||
|
|
@comment cvs.texinfo,v 1.6 1995/10/12 23:39:26 kfogel Exp
|
|||
|
|
@comment Documentation for CVS.
|
|||
|
|
@comment Copyright (C) 1992, 1993 Signum Support AB
|
|||
|
|
@comment Copyright (C) 1993 Free Software Foundation, Inc.
|
|||
|
|
|
|||
|
|
@comment This file is part of the CVS distribution.
|
|||
|
|
|
|||
|
|
@comment CVS is free software; you can redistribute it and/or modify
|
|||
|
|
@comment it under the terms of the GNU General Public License as published by
|
|||
|
|
@comment the Free Software Foundation; either version 1, or (at your option)
|
|||
|
|
@comment any later version.
|
|||
|
|
|
|||
|
|
@comment CVS is distributed in the hope that it will be useful,
|
|||
|
|
@comment but WITHOUT ANY WARRANTY; without even the implied warranty of
|
|||
|
|
@comment MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
|
|||
|
|
@comment GNU General Public License for more details.
|
|||
|
|
|
|||
|
|
@comment You should have received a copy of the GNU General Public License
|
|||
|
|
@comment along with CVS; see the file COPYING. If not, write to
|
|||
|
|
@comment the Free Software Foundation, 675 Mass Ave, Cambridge, MA 02139, USA.
|
|||
|
|
|
|||
|
|
@afourpaper
|
|||
|
|
@setfilename cvs.info
|
|||
|
|
@include CVSvn.texi
|
|||
|
|
@settitle CVS---Concurrent Versions System
|
|||
|
|
@setchapternewpage odd
|
|||
|
|
|
|||
|
|
@c -- TODO list:
|
|||
|
|
@c -- Fix all lines that match "^@c -- "
|
|||
|
|
@c -- Document how CVS finds the binaries it executes.
|
|||
|
|
@c Things to include in the index:
|
|||
|
|
@c Finding RCS binaries
|
|||
|
|
@c Path to RCS binaries
|
|||
|
|
@c RCS, how CVS finds them
|
|||
|
|
@c s/RCS/diff/
|
|||
|
|
@c -- More on binary files
|
|||
|
|
|
|||
|
|
@ifinfo
|
|||
|
|
Copyright @copyright{} 1992, 1993 Signum Support AB
|
|||
|
|
Copyright @copyright{} 1993, 1994 Free Software Foundation, Inc.
|
|||
|
|
|
|||
|
|
Permission is granted to make and distribute verbatim copies of
|
|||
|
|
this manual provided the copyright notice and this permission notice
|
|||
|
|
are preserved on all copies.
|
|||
|
|
|
|||
|
|
@ignore
|
|||
|
|
Permission is granted to process this file through Tex and print the
|
|||
|
|
results, provided the printed document carries copying permission
|
|||
|
|
notice identical to this one except for the removal of this paragraph
|
|||
|
|
(this paragraph not being relevant to the printed manual).
|
|||
|
|
|
|||
|
|
@end ignore
|
|||
|
|
Permission is granted to copy and distribute modified versions of this
|
|||
|
|
manual under the conditions for verbatim copying, provided also that the
|
|||
|
|
section entitled ``GNU General Public License'' is included exactly as
|
|||
|
|
in the original, and provided that the entire resulting derived work is
|
|||
|
|
distributed under the terms of a permission notice identical to this one.
|
|||
|
|
|
|||
|
|
Permission is granted to copy and distribute translations of this manual
|
|||
|
|
into another language, under the above conditions for modified versions,
|
|||
|
|
except that the section entitled ``GNU General Public License'' and
|
|||
|
|
this permission notice may be included in translations approved by the
|
|||
|
|
Free Software Foundation instead of in the original English.
|
|||
|
|
@end ifinfo
|
|||
|
|
|
|||
|
|
@comment The titlepage section does not appear in the Info file.
|
|||
|
|
@titlepage
|
|||
|
|
@sp 4
|
|||
|
|
@comment The title is printed in a large font.
|
|||
|
|
@center @titlefont{Version Management}
|
|||
|
|
@sp
|
|||
|
|
@center @titlefont{with}
|
|||
|
|
@sp
|
|||
|
|
@center @titlefont{CVS}
|
|||
|
|
@sp 2
|
|||
|
|
@center for @sc{cvs} @value{CVSVN}
|
|||
|
|
@comment -release-
|
|||
|
|
@sp 3
|
|||
|
|
@center Per Cederqvist et al
|
|||
|
|
|
|||
|
|
@comment The following two commands start the copyright page
|
|||
|
|
@comment for the printed manual. This will not appear in the Info file.
|
|||
|
|
@page
|
|||
|
|
@vskip 0pt plus 1filll
|
|||
|
|
Copyright @copyright{} 1992, 1993 Signum Support AB
|
|||
|
|
|
|||
|
|
Permission is granted to make and distribute verbatim copies of
|
|||
|
|
this manual provided the copyright notice and this permission notice
|
|||
|
|
are preserved on all copies.
|
|||
|
|
|
|||
|
|
Permission is granted to copy and distribute modified versions of this
|
|||
|
|
manual under the conditions for verbatim copying, provided also that the
|
|||
|
|
section entitled ``GNU General Public License'' is included exactly as
|
|||
|
|
in the original, and provided that the entire resulting derived work is
|
|||
|
|
distributed under the terms of a permission notice identical to this one.
|
|||
|
|
|
|||
|
|
Permission is granted to copy and distribute translations of this manual
|
|||
|
|
into another language, under the above conditions for modified versions,
|
|||
|
|
except that the section entitled ``GNU General Public License'' and
|
|||
|
|
this permission notice may be included in translations approved by the
|
|||
|
|
Free Software Foundation instead of in the original English.
|
|||
|
|
@end titlepage
|
|||
|
|
|
|||
|
|
@comment ================================================================
|
|||
|
|
@comment The real text starts here
|
|||
|
|
@comment ================================================================
|
|||
|
|
|
|||
|
|
@ifinfo
|
|||
|
|
@c ---------------------------------------------------------------------
|
|||
|
|
@node Top
|
|||
|
|
@top
|
|||
|
|
@c Note: there is a space after that @top command.
|
|||
|
|
@c The texinfo-format-buffer Emacs function and
|
|||
|
|
@c the makeinfo shell command disagree on what arguments
|
|||
|
|
@c @top takes; @top followed by a single space is
|
|||
|
|
@c something they can both cope with.
|
|||
|
|
|
|||
|
|
This info manual describes how to use and administer
|
|||
|
|
@sc{cvs} version @value{CVSVN}.
|
|||
|
|
@end ifinfo
|
|||
|
|
|
|||
|
|
@menu
|
|||
|
|
* Preface:: About this manual
|
|||
|
|
* What is CVS?:: What is CVS?
|
|||
|
|
* Basic concepts:: Basic concepts of revision management
|
|||
|
|
* A sample session:: A tour of basic CVS usage
|
|||
|
|
* Repository:: Where all your sources are stored
|
|||
|
|
* Starting a new project:: Starting a project with CVS
|
|||
|
|
* Multiple developers:: How CVS helps a group of developers
|
|||
|
|
* Branches:: Parallel development explained
|
|||
|
|
* Merging:: How to move changes between branches
|
|||
|
|
* Recursive behavior:: CVS descends directories
|
|||
|
|
* Adding files:: Adding files to a module
|
|||
|
|
* Removing files:: Removing files from a module
|
|||
|
|
* Tracking sources:: Tracking third-party sources
|
|||
|
|
* Moving files:: Moving and renaming files
|
|||
|
|
* Moving directories:: Moving and renaming directories
|
|||
|
|
* History browsing:: Viewing the history of files in various ways
|
|||
|
|
* Keyword substitution:: CVS can include the revision inside the file
|
|||
|
|
* Binary files:: CVS can handle binary files
|
|||
|
|
* Revision management:: Policy questions for revision management
|
|||
|
|
* Invoking CVS:: Reference manual for CVS commands
|
|||
|
|
* Administrative files:: Reference manual for the Administrative files
|
|||
|
|
* Environment variables:: All environment variables which affect CVS
|
|||
|
|
* Troubleshooting:: Some tips when nothing works
|
|||
|
|
* Copying:: GNU GENERAL PUBLIC LICENSE
|
|||
|
|
* Index:: Index
|
|||
|
|
@end menu
|
|||
|
|
|
|||
|
|
@c ---------------------------------------------------------------------
|
|||
|
|
@node Preface
|
|||
|
|
@unnumbered About this manual
|
|||
|
|
@cindex Preface
|
|||
|
|
@cindex About this manual
|
|||
|
|
|
|||
|
|
Up to this point, one of the weakest parts of @sc{cvs}
|
|||
|
|
has been the documentation. @sc{cvs} is a complex
|
|||
|
|
program. Previous versions of the manual were written
|
|||
|
|
in the manual page format, which is not really well
|
|||
|
|
suited for such a complex program.
|
|||
|
|
|
|||
|
|
When writing this manual, I had several goals in mind:
|
|||
|
|
|
|||
|
|
@itemize @bullet
|
|||
|
|
@item
|
|||
|
|
No knowledge of @sc{rcs} should be necessary.
|
|||
|
|
|
|||
|
|
@item
|
|||
|
|
No previous knowledge of revision control software
|
|||
|
|
should be necessary. All terms, such as @dfn{revision
|
|||
|
|
numbers}, @dfn{revision trees} and @dfn{merging} are
|
|||
|
|
explained as they are introduced.
|
|||
|
|
|
|||
|
|
@item
|
|||
|
|
The manual should concentrate on the things @sc{cvs} users
|
|||
|
|
want to do, instead of what the @sc{cvs} commands can do.
|
|||
|
|
The first part of this manual leads you through things
|
|||
|
|
you might want to do while doing development, and
|
|||
|
|
introduces the relevant @sc{cvs} commands as they are
|
|||
|
|
needed.
|
|||
|
|
|
|||
|
|
@item
|
|||
|
|
Information should be easy to find. In the reference
|
|||
|
|
manual in the appendices almost all information about
|
|||
|
|
every @sc{cvs} command is gathered together. There is also
|
|||
|
|
an extensive index, and a lot of cross references.
|
|||
|
|
@end itemize
|
|||
|
|
|
|||
|
|
@cindex Signum Support
|
|||
|
|
@cindex Support, getting CVS support
|
|||
|
|
This manual was contributed by Signum Support AB in
|
|||
|
|
Sweden. Signum is yet another in the growing list of
|
|||
|
|
companies that support free software. You are free to
|
|||
|
|
copy both this manual and the @sc{cvs} program.
|
|||
|
|
@xref{Copying}, for the details. Signum Support offers
|
|||
|
|
@c -- Check this reference! It has been bogus in the past.
|
|||
|
|
support contracts and binary distribution for many
|
|||
|
|
programs, such as @sc{cvs}, @sc{gnu} Emacs, the
|
|||
|
|
@sc{gnu} C compiler and others. Write to us for
|
|||
|
|
more information.
|
|||
|
|
|
|||
|
|
@example
|
|||
|
|
Signum Support AB
|
|||
|
|
Box 2044
|
|||
|
|
S-580 02 Linkoping
|
|||
|
|
Sweden
|
|||
|
|
|
|||
|
|
Email: info@@signum.se
|
|||
|
|
Phone: +46 (0)13 - 21 46 00
|
|||
|
|
Fax: +46 (0)13 - 21 47 00
|
|||
|
|
@end example
|
|||
|
|
|
|||
|
|
Another company selling support for @sc{cvs} is Cyclic
|
|||
|
|
Software, web: @code{http://www.cyclic.com/}, email:
|
|||
|
|
@code{info@@cyclic.com}.
|
|||
|
|
|
|||
|
|
@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
|
|||
|
|
@menu
|
|||
|
|
* Checklist::
|
|||
|
|
* Credits::
|
|||
|
|
* BUGS::
|
|||
|
|
@end menu
|
|||
|
|
|
|||
|
|
@node Checklist
|
|||
|
|
@unnumberedsec Checklist for the impatient reader
|
|||
|
|
|
|||
|
|
@sc{cvs} is a complex system. You will need to read
|
|||
|
|
the manual to be able to use all of its capabilities.
|
|||
|
|
There are dangers that can easily be avoided if you
|
|||
|
|
know about them, and this manual tries to warn you
|
|||
|
|
about them. This checklist is intended to help you
|
|||
|
|
avoid the dangers without reading the entire manual.
|
|||
|
|
If you intend to read the entire manual you can skip
|
|||
|
|
this table.
|
|||
|
|
|
|||
|
|
@table @asis
|
|||
|
|
@item Binary files
|
|||
|
|
@sc{cvs} can handle binary files, but
|
|||
|
|
you must have @sc{rcs} release 5.5 or later and
|
|||
|
|
a release of @sc{gnu} diff that supports the @samp{-a}
|
|||
|
|
flag (release 1.15 and later are OK). You must also
|
|||
|
|
configure both @sc{rcs} and @sc{cvs} to handle binary
|
|||
|
|
files when you install them.
|
|||
|
|
|
|||
|
|
Keword substitution can be a source of trouble with
|
|||
|
|
binary files. @xref{Keyword substitution}, for
|
|||
|
|
solutions.
|
|||
|
|
|
|||
|
|
@item The @code{admin} command
|
|||
|
|
Uncareful use of the @code{admin} command can cause
|
|||
|
|
@sc{cvs} to cease working. @xref{admin}, before trying
|
|||
|
|
to use it.
|
|||
|
|
@end table
|
|||
|
|
|
|||
|
|
@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
|
|||
|
|
@node Credits
|
|||
|
|
@unnumberedsec Credits
|
|||
|
|
|
|||
|
|
@cindex Contributors (manual)
|
|||
|
|
@cindex Credits (manual)
|
|||
|
|
Roland Pesch, Cygnus Support <@t{pesch@@cygnus.com}>
|
|||
|
|
wrote the manual pages which were distributed with
|
|||
|
|
@sc{cvs} 1.3. Appendix A and B contain much text that
|
|||
|
|
was extracted from them. He also read an early draft
|
|||
|
|
of this manual and contributed many ideas and
|
|||
|
|
corrections.
|
|||
|
|
|
|||
|
|
The mailing-list @code{info-cvs} is sometimes
|
|||
|
|
informative. I have included information from postings
|
|||
|
|
made by the following persons:
|
|||
|
|
David G. Grubbs <@t{dgg@@think.com}>.
|
|||
|
|
|
|||
|
|
Some text has been extracted from the man pages for
|
|||
|
|
@sc{rcs}.
|
|||
|
|
|
|||
|
|
The @sc{cvs} @sc{faq} (@pxref{What is CVS?}) by David
|
|||
|
|
G. Grubbs has been used as a check-list to make sure
|
|||
|
|
that this manual is as complete as possible. (This
|
|||
|
|
manual does however not include all of the material in
|
|||
|
|
the @sc{faq}). The @sc{faq} contains a lot of useful
|
|||
|
|
information.
|
|||
|
|
|
|||
|
|
In addition, the following persons have helped by
|
|||
|
|
telling me about mistakes I've made:
|
|||
|
|
Roxanne Brunskill <@t{rbrunski@@datap.ca}>,
|
|||
|
|
Kathy Dyer <@t{dyer@@phoenix.ocf.llnl.gov}>,
|
|||
|
|
Karl Pingle <@t{pingle@@acuson.com}>,
|
|||
|
|
Thomas A Peterson <@t{tap@@src.honeywell.com}>,
|
|||
|
|
Inge Wallin <@t{ingwa@@signum.se}>,
|
|||
|
|
Dirk Koschuetzki <@t{koschuet@@fmi.uni-passau.de}>
|
|||
|
|
and Michael Brown <@t{brown@@wi.extrel.com}>.
|
|||
|
|
|
|||
|
|
@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
|
|||
|
|
@node BUGS
|
|||
|
|
@unnumberedsec BUGS
|
|||
|
|
|
|||
|
|
@cindex Bugs, known in this manual
|
|||
|
|
@cindex Known bugs in this manual
|
|||
|
|
This manual is known to have room for improvement.
|
|||
|
|
Here is a list of known deficiencies:
|
|||
|
|
|
|||
|
|
@itemize @bullet
|
|||
|
|
@item
|
|||
|
|
In the examples, the output from @sc{cvs} is sometimes
|
|||
|
|
displayed, sometimes not.
|
|||
|
|
|
|||
|
|
@item
|
|||
|
|
The input that you are supposed to type in the examples
|
|||
|
|
should have a different font than the output from the
|
|||
|
|
computer.
|
|||
|
|
|
|||
|
|
@item
|
|||
|
|
This manual should be clearer about what file
|
|||
|
|
permissions you should set up in the repository, and
|
|||
|
|
about setuid/setgid.
|
|||
|
|
|
|||
|
|
@item
|
|||
|
|
Some of the chapters are not yet complete. They are
|
|||
|
|
noted by comments in the @file{cvs.texinfo} file.
|
|||
|
|
|
|||
|
|
@item
|
|||
|
|
@cindex Reporting bugs (manual)
|
|||
|
|
@cindex Bugs, reporting (manual)
|
|||
|
|
@cindex Errors, reporting (manual)
|
|||
|
|
This list is not complete. If you notice any error,
|
|||
|
|
omission, or something that is unclear, please send
|
|||
|
|
mail to @t{bug-cvs@@prep.ai.mit.edu}.
|
|||
|
|
@end itemize
|
|||
|
|
|
|||
|
|
I hope that you will find this manual useful, despite
|
|||
|
|
the above-mentioned shortcomings.
|
|||
|
|
|
|||
|
|
@flushright
|
|||
|
|
|
|||
|
|
Linkoping, October 1993
|
|||
|
|
Per Cederqvist
|
|||
|
|
@end flushright
|
|||
|
|
|
|||
|
|
@c ---------------------------------------------------------------------
|
|||
|
|
@node What is CVS?
|
|||
|
|
@chapter What is CVS?
|
|||
|
|
@cindex What is CVS?
|
|||
|
|
@cindex Introduction to CVS
|
|||
|
|
@cindex CVS, introduction to
|
|||
|
|
|
|||
|
|
@sc{cvs} is a version control system. Using it, you can
|
|||
|
|
record the history of your source files.
|
|||
|
|
|
|||
|
|
@c -- ///
|
|||
|
|
@c -- ///Those who cannot remember the past are condemned to repeat it.
|
|||
|
|
@c -- /// -- George Santayana
|
|||
|
|
@c -- //////
|
|||
|
|
|
|||
|
|
@c -- Insert history quote here!
|
|||
|
|
For example, bugs sometimes creep in when
|
|||
|
|
software is modified, and you might not detect the bug
|
|||
|
|
until a long time after you make the modification.
|
|||
|
|
With @sc{cvs}, you can easily retrieve old versions to see
|
|||
|
|
exactly which change caused the bug. This can
|
|||
|
|
sometimes be a big help.
|
|||
|
|
|
|||
|
|
You could of course save every version of every file
|
|||
|
|
you have ever created. This would
|
|||
|
|
however waste an enormous amount of disk space. @sc{cvs}
|
|||
|
|
stores all the versions of a file in a single file in a
|
|||
|
|
clever way that only stores the differences between
|
|||
|
|
versions.
|
|||
|
|
|
|||
|
|
@sc{cvs} also helps you if you are part of a group of people working
|
|||
|
|
on the same project. It is all too easy to overwrite
|
|||
|
|
each others' changes unless you are extremely careful.
|
|||
|
|
Some editors, like @sc{gnu} Emacs, try to make sure that
|
|||
|
|
the same file is never modified by two people at the
|
|||
|
|
same time. Unfortunately, if someone is using another
|
|||
|
|
editor, that safeguard will not work. @sc{cvs} solves this problem
|
|||
|
|
by insulating the different developers from each other. Every
|
|||
|
|
developer works in his own directory, and @sc{cvs} merges
|
|||
|
|
the work when each developer is done.
|
|||
|
|
|
|||
|
|
@cindex History of CVS
|
|||
|
|
@cindex CVS, history of
|
|||
|
|
@cindex Credits (CVS program)
|
|||
|
|
@cindex Contributors (CVS program)
|
|||
|
|
@sc{cvs} started out as a bunch of shell scripts written by
|
|||
|
|
Dick Grune, posted to @code{comp.sources.unix} in the volume 6
|
|||
|
|
release of December, 1986. While no actual code from
|
|||
|
|
these shell scripts is present in the current version
|
|||
|
|
of @sc{cvs} much of the @sc{cvs} conflict resolution algorithms
|
|||
|
|
come from them.
|
|||
|
|
|
|||
|
|
In April, 1989, Brian Berliner designed and coded @sc{cvs}.
|
|||
|
|
Jeff Polk later helped Brian with the design of the @sc{cvs}
|
|||
|
|
module and vendor branch support.
|
|||
|
|
|
|||
|
|
@cindex Source, getting CVS source
|
|||
|
|
You can get @sc{cvs} via anonymous ftp from a number of
|
|||
|
|
sites, for instance @t{prep.ai.mit.edu} in
|
|||
|
|
@file{pub/gnu}.
|
|||
|
|
|
|||
|
|
@cindex Mailing list
|
|||
|
|
@cindex List, mailing list
|
|||
|
|
There is a mailing list for @sc{cvs} where bug reports
|
|||
|
|
can be sent, questions can be asked, an FAQ is posted,
|
|||
|
|
and discussion about future enhancements to @sc{cvs}
|
|||
|
|
take place. To submit a message to the list, write to
|
|||
|
|
<@t{info-cvs@@prep.ai.mit.edu}>. To subscribe or
|
|||
|
|
unsubscribe, write to
|
|||
|
|
<@t{info-cvs-request@@prep.ai.mit.edu}>. Please be
|
|||
|
|
specific about your email address.
|
|||
|
|
|
|||
|
|
|
|||
|
|
@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
|
|||
|
|
@unnumberedsec CVS is not@dots{}
|
|||
|
|
|
|||
|
|
@sc{cvs} can do a lot of things for you, but it does
|
|||
|
|
not try to be everything for everyone.
|
|||
|
|
|
|||
|
|
@table @asis
|
|||
|
|
@item @sc{cvs} is not a build system.
|
|||
|
|
|
|||
|
|
Though the structure of your repository and modules
|
|||
|
|
file interact with your build system
|
|||
|
|
(e.g. @file{Makefile}s), they are essentially
|
|||
|
|
independent.
|
|||
|
|
|
|||
|
|
@sc{cvs} does not dictate how you build anything. It
|
|||
|
|
merely stores files for retrieval in a tree structure
|
|||
|
|
you devise.
|
|||
|
|
|
|||
|
|
@sc{cvs} does not dictate how to use disk space in the
|
|||
|
|
checked out working directories. If you write your
|
|||
|
|
@file{Makefile}s or scripts in every directory so they
|
|||
|
|
have to know the relative positions of everything else,
|
|||
|
|
you wind up requiring the entire repository to be
|
|||
|
|
checked out. That's simply bad planning.
|
|||
|
|
|
|||
|
|
If you modularize your work, and construct a build
|
|||
|
|
system that will share files (via links, mounts,
|
|||
|
|
@code{VPATH} in @file{Makefile}s, etc.), you can
|
|||
|
|
arrange your disk usage however you like.
|
|||
|
|
|
|||
|
|
But you have to remember that @emph{any} such system is
|
|||
|
|
a lot of work to construct and maintain. @sc{cvs} does
|
|||
|
|
not address the issues involved. 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, @file{Makefile}s,
|
|||
|
|
etc) under @sc{cvs}.
|
|||
|
|
|
|||
|
|
@item @sc{cvs} is not a substitute for management.
|
|||
|
|
|
|||
|
|
Your managers and project leaders are expected to talk
|
|||
|
|
to you frequently enough to make certain you are aware
|
|||
|
|
of schedules, merge points, branch names and release
|
|||
|
|
dates. If they don't, @sc{cvs} can't help.
|
|||
|
|
|
|||
|
|
@sc{cvs} is an instrument for making sources dance to
|
|||
|
|
your tune. But you are the piper and the composer. No
|
|||
|
|
instrument plays itself or writes its own music.
|
|||
|
|
|
|||
|
|
@item @sc{cvs} is not a substitute for developer communication.
|
|||
|
|
|
|||
|
|
When faced with conflicts within a single file, most
|
|||
|
|
developers manage to resolve them without too much
|
|||
|
|
effort. But a more general definition of ``conflict''
|
|||
|
|
includes problems too difficult to solve without
|
|||
|
|
communication between developers.
|
|||
|
|
|
|||
|
|
@sc{cvs} cannot determine when simultaneous changes
|
|||
|
|
within a single file, or across a whole collection of
|
|||
|
|
files, will logically conflict with one another. Its
|
|||
|
|
concept of a @dfn{conflict} is purely textual, arising
|
|||
|
|
when two changes to the same base file are near enough
|
|||
|
|
to spook the merge (i.e. @code{diff3}) command.
|
|||
|
|
|
|||
|
|
@sc{cvs} does not claim to help at all in figuring out
|
|||
|
|
non-textual or distributed conflicts in program logic.
|
|||
|
|
|
|||
|
|
For example: Say you change the arguments to function
|
|||
|
|
@code{X} defined in file @file{A}. At the same time,
|
|||
|
|
someone edits file @file{B}, adding new calls to
|
|||
|
|
function @code{X} using the old arguments. You are
|
|||
|
|
outside the realm of @sc{cvs}'s competence.
|
|||
|
|
|
|||
|
|
Acquire the habit of reading specs and talking to your
|
|||
|
|
peers.
|
|||
|
|
|
|||
|
|
|
|||
|
|
@item @sc{cvs} is not a configuration management system.
|
|||
|
|
|
|||
|
|
@sc{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:
|
|||
|
|
|
|||
|
|
@itemize @bullet
|
|||
|
|
@item Source control.
|
|||
|
|
@item Dependency tracking.
|
|||
|
|
@item Build systems (i.e. What to build and how to find
|
|||
|
|
things during a build. What is shared? What is local?)
|
|||
|
|
@item Bug tracking.
|
|||
|
|
@item Automated Testing procedures.
|
|||
|
|
@item Release Engineering documentation and procedures.
|
|||
|
|
@item Tape Construction.
|
|||
|
|
@item Customer Installation.
|
|||
|
|
@item A way for users to run different versions of the same
|
|||
|
|
software on the same host at the same time.
|
|||
|
|
@end itemize
|
|||
|
|
|
|||
|
|
@sc{cvs} provides only the first.
|
|||
|
|
@end table
|
|||
|
|
|
|||
|
|
This section is taken from release 2.3 of the @sc{cvs}
|
|||
|
|
@sc{faq}.
|
|||
|
|
|
|||
|
|
@c ---------------------------------------------------------------------
|
|||
|
|
@node Basic concepts
|
|||
|
|
@chapter Basic concepts
|
|||
|
|
@cindex Modules (intro)
|
|||
|
|
@cindex Repository (intro)
|
|||
|
|
|
|||
|
|
@sc{cvs} stores all files in a centralized
|
|||
|
|
@dfn{repository}: a directory (such as
|
|||
|
|
@file{/usr/local/cvsroot} or
|
|||
|
|
@file{user@@remotehost:/usr/local/cvsroot}) which is
|
|||
|
|
populated with a hierarchy of files and directories.
|
|||
|
|
(@pxref{Remote repositories} for information about
|
|||
|
|
keeping the repository on a remote machine.)
|
|||
|
|
|
|||
|
|
Normally, you never access any of the files in the
|
|||
|
|
repository directly. Instead, you use @sc{cvs}
|
|||
|
|
commands to get your own copy of the files, and then
|
|||
|
|
work on that copy. When you've finished a set of
|
|||
|
|
changes, you check (or @dfn{commit}) them back into the
|
|||
|
|
repository.
|
|||
|
|
|
|||
|
|
The files in the repository are organized in
|
|||
|
|
@dfn{modules}. Each module is made up of one or more
|
|||
|
|
files, and can include files from several directories.
|
|||
|
|
A typical usage is to define one module per project.
|
|||
|
|
|
|||
|
|
@menu
|
|||
|
|
* Revision numbers:: The meaning of a revision number
|
|||
|
|
* Versions revisions releases:: Terminology used in this manual
|
|||
|
|
@end menu
|
|||
|
|
|
|||
|
|
@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
|
|||
|
|
@node Revision numbers
|
|||
|
|
@section Revision numbers
|
|||
|
|
@cindex Revision numbers
|
|||
|
|
@cindex Revision tree
|
|||
|
|
@cindex Linear development
|
|||
|
|
@cindex Number, revision-
|
|||
|
|
@cindex Decimal revision number
|
|||
|
|
@cindex Main trunk (intro)
|
|||
|
|
@cindex Branch number
|
|||
|
|
@cindex Number, branch
|
|||
|
|
|
|||
|
|
Each version of a file has a unique @dfn{revision
|
|||
|
|
number}. Revision numbers look like @samp{1.1},
|
|||
|
|
@samp{1.2}, @samp{1.3.2.2} or even @samp{1.3.2.2.4.5}.
|
|||
|
|
A revision number always has an even number of
|
|||
|
|
period-separated decimal integers. By default revision
|
|||
|
|
1.1 is the first revision of a file. Each successive
|
|||
|
|
revision is given a new number by increasing the
|
|||
|
|
rightmost number by one. The following figure displays
|
|||
|
|
a few revisions, with newer revisions to the right.
|
|||
|
|
|
|||
|
|
@example
|
|||
|
|
+-----+ +-----+ +-----+ +-----+ +-----+
|
|||
|
|
! 1.1 !----! 1.2 !----! 1.3 !----! 1.4 !----! 1.5 !
|
|||
|
|
+-----+ +-----+ +-----+ +-----+ +-----+
|
|||
|
|
@end example
|
|||
|
|
|
|||
|
|
@sc{cvs} is not limited to linear development. The
|
|||
|
|
@dfn{revision tree} can be split into @dfn{branches},
|
|||
|
|
where each branch is a self-maintained line of
|
|||
|
|
development. Changes made on one branch can easily be
|
|||
|
|
moved back to the main trunk.
|
|||
|
|
|
|||
|
|
Each branch has a @dfn{branch number}, consisting of an
|
|||
|
|
odd number of period-separated decimal integers. The
|
|||
|
|
branch number is created by appending an integer to the
|
|||
|
|
revision number where the corresponding branch forked
|
|||
|
|
off. Having branch numbers allows more than one branch
|
|||
|
|
to be forked off from a certain revision.
|
|||
|
|
|
|||
|
|
@need 3500
|
|||
|
|
All revisions on a branch have revision numbers formed
|
|||
|
|
by appending an ordinal number to the branch number.
|
|||
|
|
The following figure illustrates branching with an
|
|||
|
|
example.
|
|||
|
|
|
|||
|
|
@example
|
|||
|
|
@group
|
|||
|
|
+-------------+
|
|||
|
|
Branch 1.2.2.3.2 -> ! 1.2.2.3.2.1 !
|
|||
|
|
/ +-------------+
|
|||
|
|
/
|
|||
|
|
/
|
|||
|
|
+---------+ +---------+ +---------+ +---------+
|
|||
|
|
Branch 1.2.2 -> _! 1.2.2.1 !----! 1.2.2.2 !----! 1.2.2.3 !----! 1.2.2.4 !
|
|||
|
|
/ +---------+ +---------+ +---------+ +---------+
|
|||
|
|
/
|
|||
|
|
/
|
|||
|
|
+-----+ +-----+ +-----+ +-----+ +-----+
|
|||
|
|
! 1.1 !----! 1.2 !----! 1.3 !----! 1.4 !----! 1.5 ! <- The main trunk
|
|||
|
|
+-----+ +-----+ +-----+ +-----+ +-----+
|
|||
|
|
!
|
|||
|
|
!
|
|||
|
|
! +---------+ +---------+ +---------+
|
|||
|
|
Branch 1.2.4 -> +---! 1.2.4.1 !----! 1.2.4.2 !----! 1.2.4.3 !
|
|||
|
|
+---------+ +---------+ +---------+
|
|||
|
|
|
|||
|
|
@end group
|
|||
|
|
@end example
|
|||
|
|
|
|||
|
|
@c -- However, at least for me the figure is not enough. I suggest more
|
|||
|
|
@c -- text to accompany it. "A picture is worth a thousand words", so you
|
|||
|
|
@c -- have to make sure the reader notices the couple of hundred words
|
|||
|
|
@c -- *you* had in mind more than the others!
|
|||
|
|
|
|||
|
|
@c -- Why an even number of segments? This section implies that this is
|
|||
|
|
@c -- how the main trunk is distinguished from branch roots, but you never
|
|||
|
|
@c -- explicitly say that this is the purpose of the [by itself rather
|
|||
|
|
@c -- surprising] restriction to an even number of segments.
|
|||
|
|
|
|||
|
|
The exact details of how the branch number is
|
|||
|
|
constructed is not something you normally need to be
|
|||
|
|
concerned about, but here is how it works: When
|
|||
|
|
@sc{cvs} creates a branch number it picks the first
|
|||
|
|
unused even integer, starting with 2. So when you want
|
|||
|
|
to create a branch from revision 6.4 it will be
|
|||
|
|
numbered 6.4.2. All branch numbers ending in a zero
|
|||
|
|
(such as 6.4.0) are used internally by @sc{cvs}
|
|||
|
|
(@pxref{Magic branch numbers}). The branch 1.1.1 has a
|
|||
|
|
special meaning. @xref{Tracking sources}.
|
|||
|
|
|
|||
|
|
@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
|
|||
|
|
@node Versions revisions releases
|
|||
|
|
@section Versions, revisions and releases
|
|||
|
|
@cindex Revisions, versions and releases
|
|||
|
|
@cindex Versions, revisions and releases
|
|||
|
|
@cindex Releases, revisions and versions
|
|||
|
|
|
|||
|
|
A file can have several versions, as described above.
|
|||
|
|
Likewise, a software product can have several versions.
|
|||
|
|
A software product is often given a version number such
|
|||
|
|
as @samp{4.1.1}.
|
|||
|
|
|
|||
|
|
Versions in the first sense are called @dfn{revisions}
|
|||
|
|
in this document, and versions in the second sense are
|
|||
|
|
called @dfn{releases}. To avoid confusion, the word
|
|||
|
|
@dfn{version} is almost never used in this document.
|
|||
|
|
|
|||
|
|
@c ---------------------------------------------------------------------
|
|||
|
|
@node A sample session
|
|||
|
|
@chapter A sample session
|
|||
|
|
@cindex A sample session
|
|||
|
|
@cindex Example of a work-session
|
|||
|
|
@cindex Getting started
|
|||
|
|
@cindex Work-session, example of
|
|||
|
|
@cindex tc, Trivial Compiler (example)
|
|||
|
|
@cindex Trivial Compiler (example)
|
|||
|
|
|
|||
|
|
This section describes a typical work-session using
|
|||
|
|
@sc{cvs}. It assumes that a repository is set up
|
|||
|
|
(@pxref{Repository}).
|
|||
|
|
|
|||
|
|
Suppose you are working on a simple compiler. The source
|
|||
|
|
consists of a handful of C files and a @file{Makefile}.
|
|||
|
|
The compiler is called @samp{tc} (Trivial Compiler),
|
|||
|
|
and the repository is set up so that there is a module
|
|||
|
|
called @samp{tc}.
|
|||
|
|
|
|||
|
|
@menu
|
|||
|
|
* Getting the source:: Creating a workspace
|
|||
|
|
* Committing your changes:: Making your work available to others
|
|||
|
|
* Cleaning up:: Cleaning up
|
|||
|
|
* Viewing differences:: Viewing differences
|
|||
|
|
@end menu
|
|||
|
|
|
|||
|
|
@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
|
|||
|
|
@node Getting the source
|
|||
|
|
@section Getting the source
|
|||
|
|
@cindex Getting the source
|
|||
|
|
@cindex Checking out source
|
|||
|
|
@cindex Fetching source
|
|||
|
|
@cindex Source, getting from CVS
|
|||
|
|
@cindex Checkout, example
|
|||
|
|
|
|||
|
|
The first thing you must do is to get your own working copy of the
|
|||
|
|
source for @samp{tc}. For this, you use the @code{checkout} command:
|
|||
|
|
|
|||
|
|
@example
|
|||
|
|
$ cvs checkout tc
|
|||
|
|
@end example
|
|||
|
|
|
|||
|
|
@noindent
|
|||
|
|
This will create a new directory called @file{tc} and populate it with
|
|||
|
|
the source files.
|
|||
|
|
|
|||
|
|
@example
|
|||
|
|
$ cd tc
|
|||
|
|
$ ls tc
|
|||
|
|
CVS Makefile backend.c driver.c frontend.c parser.c
|
|||
|
|
@end example
|
|||
|
|
|
|||
|
|
The @file{CVS} directory is used internally by
|
|||
|
|
@sc{cvs}. Normally, you should not modify or remove
|
|||
|
|
any of the files in it.
|
|||
|
|
|
|||
|
|
You start your favorite editor, hack away at @file{backend.c}, and a couple
|
|||
|
|
of hours later you have added an optimization pass to the compiler.
|
|||
|
|
A note to @sc{rcs} and @sc{sccs} users: There is no need to lock the files that
|
|||
|
|
you want to edit. @xref{Multiple developers} for an explanation.
|
|||
|
|
|
|||
|
|
@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
|
|||
|
|
@node Committing your changes
|
|||
|
|
@section Committing your changes
|
|||
|
|
@cindex Committing changes
|
|||
|
|
@cindex Log message entry
|
|||
|
|
@cindex CVSEDITOR, environment variable
|
|||
|
|
@cindex EDITOR, environment variable
|
|||
|
|
|
|||
|
|
When you have checked that the compiler is still compilable you decide
|
|||
|
|
to make a new version of @file{backend.c}.
|
|||
|
|
|
|||
|
|
@example
|
|||
|
|
$ cvs commit backend.c
|
|||
|
|
@end example
|
|||
|
|
|
|||
|
|
@noindent
|
|||
|
|
@sc{cvs} starts an editor, to allow you to enter a log
|
|||
|
|
message. You type in ``Added an optimization pass.'',
|
|||
|
|
save the temporary file, and exit the editor.
|
|||
|
|
|
|||
|
|
The environment variable @code{$CVSEDITOR} determines
|
|||
|
|
which editor is started. If @code{$CVSEDITOR} is not
|
|||
|
|
set, then if the environment variable @code{$EDITOR} is
|
|||
|
|
set, it will be used. If both @code{$CVSEDITOR} and
|
|||
|
|
@code{$EDITOR} are not set then the editor defaults to
|
|||
|
|
@code{vi}. If you want to avoid the overhead of
|
|||
|
|
starting an editor you can specify the log message on
|
|||
|
|
the command line using the @samp{-m} flag instead, like
|
|||
|
|
this:
|
|||
|
|
|
|||
|
|
@example
|
|||
|
|
$ cvs commit -m "Added an optimization pass" backend.c
|
|||
|
|
@end example
|
|||
|
|
|
|||
|
|
@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
|
|||
|
|
@node Cleaning up
|
|||
|
|
@section Cleaning up
|
|||
|
|
@cindex Cleaning up
|
|||
|
|
@cindex Working copy, removing
|
|||
|
|
@cindex Removing your working copy
|
|||
|
|
@cindex Releasing your working copy
|
|||
|
|
|
|||
|
|
Before you turn to other tasks you decide to remove your working copy of
|
|||
|
|
tc. One acceptable way to do that is of course
|
|||
|
|
|
|||
|
|
@example
|
|||
|
|
$ cd ..
|
|||
|
|
$ rm -r tc
|
|||
|
|
@end example
|
|||
|
|
|
|||
|
|
@noindent
|
|||
|
|
but a better way is to use the @code{release} command (@pxref{release}):
|
|||
|
|
|
|||
|
|
@example
|
|||
|
|
$ cd ..
|
|||
|
|
$ cvs release -d tc
|
|||
|
|
M driver.c
|
|||
|
|
? tc
|
|||
|
|
You have [1] altered files in this repository.
|
|||
|
|
Are you sure you want to release (and delete) module `tc': n
|
|||
|
|
** `release' aborted by user choice.
|
|||
|
|
@end example
|
|||
|
|
|
|||
|
|
The @code{release} command checks that all your modifications have been
|
|||
|
|
committed. If history logging is enabled it also makes a note in the
|
|||
|
|
history file. @xref{history file}.
|
|||
|
|
|
|||
|
|
When you use the @samp{-d} flag with @code{release}, it
|
|||
|
|
also removes your working copy.
|
|||
|
|
|
|||
|
|
In the example above, the @code{release} command wrote a couple of lines
|
|||
|
|
of output. @samp{? tc} means that the file @file{tc} is unknown to @sc{cvs}.
|
|||
|
|
That is nothing to worry about: @file{tc} is the executable compiler,
|
|||
|
|
and it should not be stored in the repository. @xref{cvsignore},
|
|||
|
|
for information about how to make that warning go away.
|
|||
|
|
@xref{release output}, for a complete explanation of
|
|||
|
|
all possible output from @code{release}.
|
|||
|
|
|
|||
|
|
@samp{M driver.c} is more serious. It means that the
|
|||
|
|
file @file{driver.c} has been modified since it was
|
|||
|
|
checked out.
|
|||
|
|
|
|||
|
|
The @code{release} command always finishes by telling
|
|||
|
|
you how many modified files you have in your working
|
|||
|
|
copy of the sources, and then asks you for confirmation
|
|||
|
|
before deleting any files or making any note in the
|
|||
|
|
history file.
|
|||
|
|
|
|||
|
|
You decide to play it safe and answer @kbd{n @key{RET}}
|
|||
|
|
when @code{release} asks for confirmation.
|
|||
|
|
|
|||
|
|
@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
|
|||
|
|
@node Viewing differences
|
|||
|
|
@section Viewing differences
|
|||
|
|
@cindex Viewing differences
|
|||
|
|
@cindex Diff
|
|||
|
|
|
|||
|
|
You do not remember modifying @file{driver.c}, so you want to see what
|
|||
|
|
has happened to that file.
|
|||
|
|
|
|||
|
|
@example
|
|||
|
|
$ cd tc
|
|||
|
|
$ cvs diff driver.c
|
|||
|
|
@end example
|
|||
|
|
|
|||
|
|
This command runs @code{diff} to compare the version of @file{driver.c}
|
|||
|
|
that you checked out with your working copy. When you see the output
|
|||
|
|
you remember that you added a command line option that enabled the
|
|||
|
|
optimization pass. You check it in, and release the module.
|
|||
|
|
|
|||
|
|
@example
|
|||
|
|
$ cvs commit -m "Added an optimization pass" driver.c
|
|||
|
|
Checking in driver.c;
|
|||
|
|
/usr/local/cvsroot/tc/driver.c,v <-- driver.c
|
|||
|
|
new revision: 1.2; previous revision: 1.1
|
|||
|
|
done
|
|||
|
|
$ cd ..
|
|||
|
|
$ cvs release -d tc
|
|||
|
|
? tc
|
|||
|
|
You have [0] altered files in this repository.
|
|||
|
|
Are you sure you want to release (and delete) module `tc': y
|
|||
|
|
@end example
|
|||
|
|
|
|||
|
|
@c ---------------------------------------------------------------------
|
|||
|
|
@node Repository
|
|||
|
|
@chapter The Repository
|
|||
|
|
@cindex Repository, example
|
|||
|
|
@cindex Layout of repository
|
|||
|
|
@cindex Typical repository
|
|||
|
|
@cindex CVSROOT, environment variable
|
|||
|
|
@cindex .profile
|
|||
|
|
@cindex .cshrc
|
|||
|
|
@cindex .tcshrc
|
|||
|
|
@cindex .bashrc
|
|||
|
|
@cindex /usr/local/cvsroot
|
|||
|
|
@cindex cvsroot
|
|||
|
|
|
|||
|
|
Figure 3 below shows a typical setup of a repository.
|
|||
|
|
Only directories are shown below.
|
|||
|
|
|
|||
|
|
@example
|
|||
|
|
@t{/usr}
|
|||
|
|
|
|
|||
|
|
+--@t{local}
|
|||
|
|
| |
|
|||
|
|
| +--@t{cvsroot}
|
|||
|
|
| | |
|
|||
|
|
| | +--@t{CVSROOT}
|
|||
|
|
| (administrative files)
|
|||
|
|
|
|
|||
|
|
+--@t{gnu}
|
|||
|
|
| |
|
|||
|
|
| +--@t{diff}
|
|||
|
|
| | (source code to @sc{gnu} diff)
|
|||
|
|
| |
|
|||
|
|
| +--@t{rcs}
|
|||
|
|
| | (source code to @sc{rcs})
|
|||
|
|
| |
|
|||
|
|
| +--@t{cvs}
|
|||
|
|
| (source code to @sc{cvs})
|
|||
|
|
|
|
|||
|
|
+--@t{yoyodyne}
|
|||
|
|
|
|
|||
|
|
+--@t{tc}
|
|||
|
|
| |
|
|||
|
|
| +--@t{man}
|
|||
|
|
| |
|
|||
|
|
| +--@t{testing}
|
|||
|
|
|
|
|||
|
|
+--(other Yoyodyne software)
|
|||
|
|
@end example
|
|||
|
|
|
|||
|
|
|
|||
|
|
There are a couple of different ways to tell @sc{cvs}
|
|||
|
|
where to find the repository. You can name the
|
|||
|
|
repository on the command line explicitly, with the
|
|||
|
|
@code{-d} (for "directory") option:
|
|||
|
|
|
|||
|
|
@example
|
|||
|
|
cvs -d /usr/local/cvsroot checkout yoyodyne/tc
|
|||
|
|
@end example
|
|||
|
|
|
|||
|
|
Or you can set the @code{$CVSROOT} environment
|
|||
|
|
variable to an absolute path to the root of the
|
|||
|
|
repository, @file{/usr/local/cvsroot} in this example.
|
|||
|
|
To set @code{$CVSROOT}, all @code{csh} and @code{tcsh}
|
|||
|
|
users should have this line in their @file{.cshrc} or
|
|||
|
|
@file{.tcshrc} files:
|
|||
|
|
|
|||
|
|
@example
|
|||
|
|
setenv CVSROOT /usr/local/cvsroot
|
|||
|
|
@end example
|
|||
|
|
|
|||
|
|
@noindent
|
|||
|
|
@code{sh} and @code{bash} users should instead have these lines in their
|
|||
|
|
@file{.profile} or @file{.bashrc}:
|
|||
|
|
|
|||
|
|
@example
|
|||
|
|
CVSROOT=/usr/local/cvsroot
|
|||
|
|
export CVSROOT
|
|||
|
|
@end example
|
|||
|
|
|
|||
|
|
A repository specified with @code{-d} will
|
|||
|
|
override the @code{$CVSROOT} environment variable.
|
|||
|
|
Once you've checked a working copy out from the
|
|||
|
|
repository, it will remember where its repository is
|
|||
|
|
(the information is recorded in the
|
|||
|
|
@file{CVS/Root} file in the working copy).
|
|||
|
|
|
|||
|
|
The @code{-d} option and the @file{CVS/Root} file
|
|||
|
|
both override the @code{$CVSROOT} environment variable;
|
|||
|
|
however, @sc{CVS} will complain if the @file{-d}
|
|||
|
|
argument and the @file{CVS/Root} file disagree.
|
|||
|
|
|
|||
|
|
There is nothing magical about the name
|
|||
|
|
@file{/usr/local/cvsroot}. You can choose to place the
|
|||
|
|
repository anywhere you like.
|
|||
|
|
@xref{Remote repositories} to learn how the repository can be on a
|
|||
|
|
different machine than your working copy of the sources.
|
|||
|
|
|
|||
|
|
The repository is split in two parts. @file{$CVSROOT/CVSROOT} contains
|
|||
|
|
administrative files for @sc{cvs}. The other directories contain the actual
|
|||
|
|
user-defined modules.
|
|||
|
|
|
|||
|
|
@menu
|
|||
|
|
* User modules:: The structure of the repository
|
|||
|
|
* Intro administrative files:: Defining modules
|
|||
|
|
* Multiple repositories:: Multiple repositories
|
|||
|
|
* Creating a repository:: Creating a repository
|
|||
|
|
* Remote repositories:: Accessing repositories on remote machines
|
|||
|
|
@end menu
|
|||
|
|
|
|||
|
|
@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
|
|||
|
|
@node User modules
|
|||
|
|
@section User modules
|
|||
|
|
@cindex User modules
|
|||
|
|
@cindex Repository, user parts
|
|||
|
|
|
|||
|
|
@example
|
|||
|
|
@code{$CVSROOT}
|
|||
|
|
|
|
|||
|
|
+--@t{yoyodyne}
|
|||
|
|
| |
|
|||
|
|
| +--@t{tc}
|
|||
|
|
| | |
|
|||
|
|
+--@t{Makefile,v}
|
|||
|
|
+--@t{backend.c,v}
|
|||
|
|
+--@t{driver.c,v}
|
|||
|
|
+--@t{frontend.c,v}
|
|||
|
|
+--@t{parser.c,v}
|
|||
|
|
+--@t{man}
|
|||
|
|
| |
|
|||
|
|
| +--@t{tc.1,v}
|
|||
|
|
|
|
|||
|
|
+--@t{testing}
|
|||
|
|
|
|
|||
|
|
+--@t{testpgm.t,v}
|
|||
|
|
+--@t{test2.t,v}
|
|||
|
|
@end example
|
|||
|
|
|
|||
|
|
@cindex History files
|
|||
|
|
@cindex RCS history files
|
|||
|
|
@cindex RCS, CVS uses RCS
|
|||
|
|
The figure above shows the contents of the @samp{tc}
|
|||
|
|
module inside the repository. As you can see all file
|
|||
|
|
names end in @samp{,v}. The files are @dfn{history
|
|||
|
|
files}. They contain, among other things, enough
|
|||
|
|
information to recreate any revision of the file, a log
|
|||
|
|
of all commit messages and the user-name of the person
|
|||
|
|
who committed the revision. @sc{cvs} uses the
|
|||
|
|
facilities of @sc{rcs}, a simpler version control
|
|||
|
|
system, to maintain these files. For a full
|
|||
|
|
description of the file format, see the @code{man} page
|
|||
|
|
@cite{rcsfile(5)}.
|
|||
|
|
@c -- Use this format for all references to man pages,
|
|||
|
|
@c -- or use something better!
|
|||
|
|
|
|||
|
|
@menu
|
|||
|
|
* File permissions:: File permissions
|
|||
|
|
@end menu
|
|||
|
|
|
|||
|
|
@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
|
|||
|
|
@node File permissions
|
|||
|
|
@subsection File permissions
|
|||
|
|
@c -- Move this to @node Setting up
|
|||
|
|
@cindex Security
|
|||
|
|
@cindex File permissions
|
|||
|
|
@cindex Group
|
|||
|
|
All @samp{,v} files are created read-only, and you
|
|||
|
|
should not change the permission of those files. The
|
|||
|
|
directories inside the repository should be writable by
|
|||
|
|
the persons that have permission to modify the files in
|
|||
|
|
each directory. This normally means that you must
|
|||
|
|
create a UNIX group (see group(5)) consisting of the
|
|||
|
|
persons that are to edit the files in a project, and
|
|||
|
|
set up the repository so that it is that group that
|
|||
|
|
owns the directory.
|
|||
|
|
|
|||
|
|
This means that you can only control access to files on
|
|||
|
|
a per-directory basis.
|
|||
|
|
|
|||
|
|
@sc{cvs} tries to set up reasonable file permissions
|
|||
|
|
for new directories that are added inside the tree, but
|
|||
|
|
you must fix the permissions manually when a new
|
|||
|
|
directory should have different permissions than its
|
|||
|
|
parent directory.
|
|||
|
|
|
|||
|
|
@cindex setuid
|
|||
|
|
@cindex setgid
|
|||
|
|
Since @sc{cvs} was not written to be run setuid, it is
|
|||
|
|
unsafe to try to run it setuid. You cannot use the
|
|||
|
|
setuid features of @sc{rcs} together with @sc{cvs}.
|
|||
|
|
|
|||
|
|
@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
|
|||
|
|
@node Intro administrative files
|
|||
|
|
@section The administrative files
|
|||
|
|
@cindex Administrative files (intro)
|
|||
|
|
@cindex Modules file
|
|||
|
|
@cindex CVSROOT, module name
|
|||
|
|
@cindex Defining modules (intro)
|
|||
|
|
|
|||
|
|
The directory @file{$CVSROOT/CVSROOT} contains some @dfn{administrative
|
|||
|
|
files}. @xref{Administrative files}, for a complete description.
|
|||
|
|
You can use @sc{cvs} without any of these files, but
|
|||
|
|
some commands work better when at least the
|
|||
|
|
@file{modules} file is properly set up.
|
|||
|
|
|
|||
|
|
The most important of these files is the @file{modules}
|
|||
|
|
file. It defines all modules in the repository. This
|
|||
|
|
is a sample @file{modules} file.
|
|||
|
|
|
|||
|
|
@c FIXME: The CVSROOT line is a goofy example now that
|
|||
|
|
@c mkmodules doesn't exist.
|
|||
|
|
@example
|
|||
|
|
CVSROOT CVSROOT
|
|||
|
|
modules CVSROOT modules
|
|||
|
|
cvs gnu/cvs
|
|||
|
|
rcs gnu/rcs
|
|||
|
|
diff gnu/diff
|
|||
|
|
tc yoyodyne/tc
|
|||
|
|
@end example
|
|||
|
|
|
|||
|
|
The @file{modules} file is line oriented. In its simplest form each
|
|||
|
|
line contains the name of the module, whitespace, and the directory
|
|||
|
|
where the module resides. The directory is a path relative to
|
|||
|
|
@code{$CVSROOT}. The last for lines in the example
|
|||
|
|
above are examples of such lines.
|
|||
|
|
|
|||
|
|
@c FIXME: might want to introduce the concept of options in modules file
|
|||
|
|
@c (the old example which was here, -i mkmodules, is obsolete).
|
|||
|
|
|
|||
|
|
The line that defines the module called @samp{modules}
|
|||
|
|
uses features that are not explained here.
|
|||
|
|
@xref{modules}, for a full explanation of all the
|
|||
|
|
available features.
|
|||
|
|
|
|||
|
|
@subsection Editing administrative files
|
|||
|
|
@cindex Editing administrative files
|
|||
|
|
@cindex Administrative files, editing them
|
|||
|
|
|
|||
|
|
You edit the administrative files in the same way that you would edit
|
|||
|
|
any other module. Use @samp{cvs checkout CVSROOT} to get a working
|
|||
|
|
copy, edit it, and commit your changes in the normal way.
|
|||
|
|
|
|||
|
|
It is possible to commit an erroneous administrative
|
|||
|
|
file. You can often fix the error and check in a new
|
|||
|
|
revision, but sometimes a particularly bad error in the
|
|||
|
|
administrative file makes it impossible to commit new
|
|||
|
|
revisions.
|
|||
|
|
@c @xref{Bad administrative files} for a hint
|
|||
|
|
@c about how to solve such situations.
|
|||
|
|
@c -- administrative file checking--
|
|||
|
|
|
|||
|
|
@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
|
|||
|
|
@node Multiple repositories
|
|||
|
|
@section Multiple repositories
|
|||
|
|
@cindex Multiple repositories
|
|||
|
|
@cindex Repositories, multiple
|
|||
|
|
@cindex Many repositories
|
|||
|
|
@cindex Parallel repositories
|
|||
|
|
@cindex Disjoint repositories
|
|||
|
|
@cindex CVSROOT, multiple repositories
|
|||
|
|
|
|||
|
|
In some situations it is a good idea to have more than
|
|||
|
|
one repository, for instance if you have two
|
|||
|
|
development groups that work on separate projects
|
|||
|
|
without sharing any code. All you have to do to have
|
|||
|
|
several repositories is to specify the appropriate
|
|||
|
|
repository, using the @code{CVSROOT} environment
|
|||
|
|
variable, the @samp{-d} option to @sc{cvs}, or (once
|
|||
|
|
you have checked out a working directories) by
|
|||
|
|
simply allowing @sc{cvs} to use the repository that was
|
|||
|
|
used to check out the working directory (@pxref{Repository}).
|
|||
|
|
|
|||
|
|
Notwithstanding, it can be confusing to have two or
|
|||
|
|
more repositories.
|
|||
|
|
|
|||
|
|
None of the examples in this manual show multiple
|
|||
|
|
repositories.
|
|||
|
|
|
|||
|
|
@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
|
|||
|
|
@node Creating a repository
|
|||
|
|
@section Creating a repository
|
|||
|
|
@c -- Well, how do you do?
|
|||
|
|
|
|||
|
|
See the instructions in the @file{INSTALL} file in the
|
|||
|
|
@sc{cvs} distribution.
|
|||
|
|
|
|||
|
|
@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
|
|||
|
|
@node Remote repositories
|
|||
|
|
@section Remote repositories
|
|||
|
|
@cindex Repositories, remote
|
|||
|
|
@cindex Remote repositories
|
|||
|
|
@cindex Client/Server Operation
|
|||
|
|
|
|||
|
|
Your working copy of the sources can be on a
|
|||
|
|
different machine than the repository. Generally,
|
|||
|
|
using a remote repository is just like using a local
|
|||
|
|
one, except that the format of the repository name is:
|
|||
|
|
|
|||
|
|
@example
|
|||
|
|
user@@hostname:/path/to/repository
|
|||
|
|
@end example
|
|||
|
|
|
|||
|
|
The details of exactly what needs to be set up depend
|
|||
|
|
on how you are connecting to the server.
|
|||
|
|
|
|||
|
|
@menu
|
|||
|
|
* Connecting via rsh:: Using the @code{rsh} program to connect
|
|||
|
|
* Password authenticated:: Direct connections using passwords
|
|||
|
|
* Kerberos authenticated:: Direct connections with kerberos
|
|||
|
|
@end menu
|
|||
|
|
|
|||
|
|
@node Connecting via rsh
|
|||
|
|
@subsection Connecting with rsh
|
|||
|
|
|
|||
|
|
@cindex rsh
|
|||
|
|
CVS uses the @file{rsh} protocol to perform these
|
|||
|
|
operations, so the remote user host needs to have a
|
|||
|
|
@file{.rhosts} file which grants access to the local
|
|||
|
|
user.
|
|||
|
|
|
|||
|
|
For example, suppose you are the user @file{mozart} on
|
|||
|
|
the local machine @file{anklet.grunge.com}, and the
|
|||
|
|
server machine is @file{chainsaw.brickyard.com}. On
|
|||
|
|
chainsaw, put the following line into the file
|
|||
|
|
@file{.rhosts} in @file{bach}'s home directory:
|
|||
|
|
|
|||
|
|
@example
|
|||
|
|
anklet.grunge.com mozart
|
|||
|
|
@end example
|
|||
|
|
|
|||
|
|
Then test that @code{rsh} is working with
|
|||
|
|
|
|||
|
|
@example
|
|||
|
|
rsh -l bach chainsaw.brickyard.com echo $PATH
|
|||
|
|
@end example
|
|||
|
|
|
|||
|
|
@cindex CVS_SERVER
|
|||
|
|
Next you have to make sure that @code{rsh} will be able
|
|||
|
|
to find the server. Make sure that the path which
|
|||
|
|
@code{rsh} printed in the above example includes the
|
|||
|
|
directory containing a program named @code{cvs} which
|
|||
|
|
is the server. You need to set the path in
|
|||
|
|
@file{.bashrc}, @file{.cshrc}, etc., not @file{.login}
|
|||
|
|
or @file{.profile}. Alternately, you can set the
|
|||
|
|
environment variable @code{CVS_SERVER} on the client
|
|||
|
|
machine to the filename of the server you want to use,
|
|||
|
|
for example @file{/usr/local/bin/cvs-1.6}.
|
|||
|
|
|
|||
|
|
There is no need to edit @code{inetd.conf} or start a
|
|||
|
|
@sc{cvs} server daemon.
|
|||
|
|
|
|||
|
|
Continuing our example, supposing you want to access
|
|||
|
|
the module @file{foo} in the repository
|
|||
|
|
@file{/usr/local/cvsroot/}, on machine
|
|||
|
|
@file{chainsaw.brickyard.com}, you are ready to go:
|
|||
|
|
|
|||
|
|
@example
|
|||
|
|
cvs -d bach@@chainsaw.brickyard.com:/user/local/cvsroot checkout foo
|
|||
|
|
@end example
|
|||
|
|
|
|||
|
|
(The @file{bach@@} can be omitted if the username is
|
|||
|
|
the same on both the local and remote hosts.)
|
|||
|
|
|
|||
|
|
@node Password authenticated
|
|||
|
|
@subsection Direct connection with password authentication
|
|||
|
|
|
|||
|
|
The @sc{cvs} client can also connect to the server
|
|||
|
|
using a password protocol. This is particularly useful
|
|||
|
|
if using @code{rsh} is not feasible (for example,
|
|||
|
|
the server is behind a firewall), and Kerberos also is
|
|||
|
|
not available.
|
|||
|
|
|
|||
|
|
To use this method, it is necessary to make
|
|||
|
|
some adjustments on both the server and client sides.
|
|||
|
|
|
|||
|
|
@menu
|
|||
|
|
* Password authentication server:: Setting up the server
|
|||
|
|
* Password authentication client:: Using the client
|
|||
|
|
* Password authentication security:: What this method does and does not do
|
|||
|
|
@end menu
|
|||
|
|
|
|||
|
|
@node Password authentication server
|
|||
|
|
@subsubsection Setting up the server for password authentication
|
|||
|
|
|
|||
|
|
@cindex Pserver (subcommand)
|
|||
|
|
@cindex password server, setting up
|
|||
|
|
@cindex authenticating server, setting up
|
|||
|
|
On the server side, the file @file{/etc/inetd.conf}
|
|||
|
|
needs to be edited so @code{inetd} knows to run the
|
|||
|
|
command @code{cvs pserver} when it receives a
|
|||
|
|
connection on the right port. By default, the port
|
|||
|
|
number is 2401; it would be different if your client
|
|||
|
|
were compiled with @code{CVS_AUTH_PORT} defined to
|
|||
|
|
something else, though.
|
|||
|
|
|
|||
|
|
If your @code{inetd} allows raw port numbers in
|
|||
|
|
@file{/etc/inetd.conf}, then the following (all on a
|
|||
|
|
single line in @file{inetd.conf}) should be sufficient:
|
|||
|
|
|
|||
|
|
@example
|
|||
|
|
2401 stream tcp nowait root /usr/local/bin/cvs
|
|||
|
|
cvs -b /usr/local/bin pserver
|
|||
|
|
@end example
|
|||
|
|
|
|||
|
|
The @samp{-b} option specifies the directory which contains
|
|||
|
|
the @sc{rcs} binaries on the server.
|
|||
|
|
|
|||
|
|
If your @code{inetd} wants a symbolic service
|
|||
|
|
name instead of a raw port number, then put this in
|
|||
|
|
@file{/etc/services}:
|
|||
|
|
|
|||
|
|
@example
|
|||
|
|
cvspserver 2401/tcp
|
|||
|
|
@end example
|
|||
|
|
|
|||
|
|
and put @code{cvspserver} instead of
|
|||
|
|
@code{2401} in @file{inetd.conf}.
|
|||
|
|
|
|||
|
|
Once the above is taken care of, restart your
|
|||
|
|
@code{inetd}, or do whatever is necessary to force it
|
|||
|
|
to reread its initialization files.
|
|||
|
|
|
|||
|
|
@cindex CVS passwd file
|
|||
|
|
@cindex passwd file
|
|||
|
|
Because the client stores and transmits passwords in
|
|||
|
|
cleartext (almost---see @ref{Password authentication
|
|||
|
|
security} for details), a separate @sc{cvs} password
|
|||
|
|
file may be used, so people don't compromise their
|
|||
|
|
regular passwords when they access the repository.
|
|||
|
|
This file is @file{$CVSROOT/CVSROOT/passwd}
|
|||
|
|
(@pxref{Intro administrative files}). Its format is
|
|||
|
|
similar to @file{/etc/passwd}, except that it only has
|
|||
|
|
two fields, username and password. For example:
|
|||
|
|
|
|||
|
|
@example
|
|||
|
|
bach:ULtgRLXo7NRxs
|
|||
|
|
cwang:1sOp854gDF3DY
|
|||
|
|
@end example
|
|||
|
|
|
|||
|
|
The password is encrypted according to the standard
|
|||
|
|
Unix @code{crypt()} function, so it is possible to
|
|||
|
|
paste in passwords directly from regular Unix
|
|||
|
|
@file{passwd} files.
|
|||
|
|
|
|||
|
|
When authenticating a password, the server first checks
|
|||
|
|
for the user in the @sc{cvs} @file{passwd} file. If it
|
|||
|
|
finds the user, it compares against that password. If
|
|||
|
|
it does not find the user, or if the @sc{cvs}
|
|||
|
|
@file{passwd} file does not exist, then the server
|
|||
|
|
tries to match the password using the system's
|
|||
|
|
user-lookup routine. When using the @sc{cvs}
|
|||
|
|
@file{passwd} file, the server runs under as the
|
|||
|
|
username specified in the the third argument in the
|
|||
|
|
entry, or as the first argument if there is no third
|
|||
|
|
argument (in this way @sc{cvs} allows imaginary
|
|||
|
|
usernames provided the @sc{cvs} @file{passwd} file
|
|||
|
|
indicates corresponding valid system usernames). In
|
|||
|
|
any case, @sc{cvs} will have no privileges which the
|
|||
|
|
(valid) user would not have.
|
|||
|
|
|
|||
|
|
Right now, the only way to put a password in the
|
|||
|
|
@sc{cvs} @file{passwd} file is to paste it there from
|
|||
|
|
somewhere else. Someday, there may be a @code{cvs
|
|||
|
|
passwd} command.
|
|||
|
|
|
|||
|
|
@node Password authentication client
|
|||
|
|
@subsubsection Using the client with password authentication
|
|||
|
|
@cindex Login (subcommand)
|
|||
|
|
@cindex password client, using
|
|||
|
|
@cindex authenticated client, using
|
|||
|
|
Before connecting to the server, the client must @dfn{log
|
|||
|
|
in} with the command @code{cvs login}. Logging in
|
|||
|
|
verifies a password with the server, and also records
|
|||
|
|
the password for later transactions with the server.
|
|||
|
|
The @code{cvs login} command needs to know the
|
|||
|
|
username, server hostname, and full repository path,
|
|||
|
|
and it gets this information from the repository
|
|||
|
|
argument or the @code{CVSROOT} environment variable.
|
|||
|
|
|
|||
|
|
@code{cvs login} is interactive --- it prompts for a
|
|||
|
|
password:
|
|||
|
|
|
|||
|
|
@example
|
|||
|
|
cvs -d bach@@chainsaw.brickyard.com:/usr/local/cvsroot login
|
|||
|
|
CVS password:
|
|||
|
|
@end example
|
|||
|
|
|
|||
|
|
The password is checked with the server; if it is
|
|||
|
|
correct, the @code{login} succeeds, else it fails,
|
|||
|
|
complaining that the password was incorrect.
|
|||
|
|
|
|||
|
|
Once you have logged in, you can force @sc{cvs} to
|
|||
|
|
connect directly to the server and authenticate with
|
|||
|
|
the stored password by prefixing the repository with
|
|||
|
|
@samp{:pserver:}:
|
|||
|
|
|
|||
|
|
@example
|
|||
|
|
cvs -d :pserver:bach@@chainsaw.brickyard.com:/usr/local/cvsroot checkout foo
|
|||
|
|
@end example
|
|||
|
|
|
|||
|
|
The @samp{:pserver:} is necessary because without it,
|
|||
|
|
@sc{cvs} will assume it should use @code{rsh} to
|
|||
|
|
connect with the server (@pxref{Connecting via rsh}).
|
|||
|
|
(Once you have a working copy checked out and are
|
|||
|
|
running @sc{cvs} commands from within it, there is no
|
|||
|
|
longer any need to specify the repository explicitly,
|
|||
|
|
because @sc{cvs} records it in the working copy's
|
|||
|
|
@file{CVS} subdirectory.)
|
|||
|
|
|
|||
|
|
@cindex CVS_PASSFILE, environment variable
|
|||
|
|
Passwords are stored by default in the file
|
|||
|
|
@file{$HOME/.cvspass}. Its format is human-readable,
|
|||
|
|
but don't edit it unless you know what you are doing.
|
|||
|
|
The passwords are not stored in cleartext, but are
|
|||
|
|
trivially encoded to protect them from "innocent"
|
|||
|
|
compromise (i.e., inadvertently being seen by a system
|
|||
|
|
administrator who happens to look at that file).
|
|||
|
|
|
|||
|
|
The @code{CVS_PASSFILE} environment variable overrides
|
|||
|
|
this default. If you use this variable, make sure you
|
|||
|
|
set it @emph{before} @code{cvs login} is run. If you
|
|||
|
|
were to set it after running @code{cvs login}, then
|
|||
|
|
later @sc{cvs} commands would be unable to look up the
|
|||
|
|
password for transmission to the server.
|
|||
|
|
|
|||
|
|
@cindex CVS_PASSWORD, environment variable
|
|||
|
|
The @code{CVS_PASSWORD} environment variable overrides
|
|||
|
|
@emph{all} stored passwords. If it is set, @sc{cvs}
|
|||
|
|
will use it for all password-authenticated
|
|||
|
|
connections.
|
|||
|
|
|
|||
|
|
@node Password authentication security
|
|||
|
|
@subsubsection Security considerations with password authentication
|
|||
|
|
|
|||
|
|
The passwords are stored on the client side in a
|
|||
|
|
trivial encoding of the cleartext, and transmitted in
|
|||
|
|
the same encoding. The encoding is done only to
|
|||
|
|
prevent inadvertent password compromises (i.e., a
|
|||
|
|
system administrator accidentally looking at the file),
|
|||
|
|
and will not prevent even a naive attacker from gaining
|
|||
|
|
the password.
|
|||
|
|
|
|||
|
|
The separate @sc{cvs} password file (@pxref{Password
|
|||
|
|
authentication server}) allows people
|
|||
|
|
to use a different password for repository access than
|
|||
|
|
for login access. On the other hand, once a user has
|
|||
|
|
access to the repository, she can execute programs on
|
|||
|
|
the server system through a variety of means. Thus, repository
|
|||
|
|
access implies fairly broad system access as well. It
|
|||
|
|
might be possible to modify @sc{cvs} to prevent that,
|
|||
|
|
but no one has done so as of this writing.
|
|||
|
|
Furthermore, there may be other ways in which having
|
|||
|
|
access to @sc{cvs} allows people to gain more general
|
|||
|
|
access to the system; noone has done a careful audit.
|
|||
|
|
|
|||
|
|
In summary, anyone who gets the password gets
|
|||
|
|
repository access, and some measure of general system
|
|||
|
|
access as well. The password is available to anyone
|
|||
|
|
who can sniff network packets or read a protected
|
|||
|
|
(i.e., user read-only) file. If you want real
|
|||
|
|
security, get Kerberos.
|
|||
|
|
|
|||
|
|
@node Kerberos authenticated
|
|||
|
|
@subsection Direct connection with kerberos
|
|||
|
|
|
|||
|
|
@cindex kerberos
|
|||
|
|
The main disadvantage of using rsh is that all the data
|
|||
|
|
needs to pass through additional programs, so it may be
|
|||
|
|
slower. So if you have kerberos installed you can
|
|||
|
|
connect via a direct @sc{tcp} connection,
|
|||
|
|
authenticating with kerberos (note that the data
|
|||
|
|
transmitted is @emph{not} encrypted).
|
|||
|
|
|
|||
|
|
To do this, @sc{cvs} needs to be compiled with kerberos
|
|||
|
|
support; when configuring @sc{cvs} it tries to detect
|
|||
|
|
whether kerberos is present or you can use the
|
|||
|
|
@file{--with-krb4} flag to configure.
|
|||
|
|
|
|||
|
|
@cindex CVS_CLIENT_PORT
|
|||
|
|
You need to edit @code{inetd.conf} on the server
|
|||
|
|
machine to run @code{cvs kserver}. The client uses
|
|||
|
|
port 1999 by default; if you want to use another port
|
|||
|
|
specify it in the @code{CVS_CLIENT_PORT} environment
|
|||
|
|
variable on the client. Set @code{CVS_CLIENT_PORT} to
|
|||
|
|
@samp{-1} to force an rsh connection.
|
|||
|
|
|
|||
|
|
@cindex kinit
|
|||
|
|
When you want to use @sc{cvs}, get a ticket in the
|
|||
|
|
usual way (generally @code{kinit}); it must be a ticket
|
|||
|
|
which allows you to log into the server machine. Then
|
|||
|
|
you are ready to go:
|
|||
|
|
|
|||
|
|
@example
|
|||
|
|
cvs -d chainsaw.brickyard.com:/user/local/cvsroot checkout foo
|
|||
|
|
@end example
|
|||
|
|
|
|||
|
|
If @sc{cvs} fails to connect, it will fall back to
|
|||
|
|
trying rsh.
|
|||
|
|
|
|||
|
|
@c ---------------------------------------------------------------------
|
|||
|
|
@node Starting a new project
|
|||
|
|
@chapter Starting a project with CVS
|
|||
|
|
@cindex Starting a project with CVS
|
|||
|
|
@cindex Creating a project
|
|||
|
|
|
|||
|
|
@comment --moduledb--
|
|||
|
|
Since @sc{cvs} 1.x is bad at renaming files and moving
|
|||
|
|
them between directories, the first thing you do when
|
|||
|
|
you start a new project should be to think through your
|
|||
|
|
file organization. It is not impossible---just
|
|||
|
|
awkward---to rename or move files.
|
|||
|
|
@xref{Moving files}.
|
|||
|
|
|
|||
|
|
What to do next depends on the situation at hand.
|
|||
|
|
|
|||
|
|
@menu
|
|||
|
|
* Setting up the files:: Getting the files into the repository
|
|||
|
|
* Defining the module:: How to make a module of the files
|
|||
|
|
@end menu
|
|||
|
|
@c -- File permissions!
|
|||
|
|
|
|||
|
|
@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
|
|||
|
|
@node Setting up the files
|
|||
|
|
@section Setting up the files
|
|||
|
|
|
|||
|
|
The first step is to create the files inside the repository. This can
|
|||
|
|
be done in a couple of different ways.
|
|||
|
|
|
|||
|
|
@c -- The contributed scripts
|
|||
|
|
@menu
|
|||
|
|
* From files:: This method is useful with old projects
|
|||
|
|
where files already exists.
|
|||
|
|
* From other version control systems:: Old projects where you want to
|
|||
|
|
preserve history from another system.
|
|||
|
|
* From scratch:: Creating a module from scratch.
|
|||
|
|
@end menu
|
|||
|
|
|
|||
|
|
@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
|
|||
|
|
@node From files
|
|||
|
|
@subsection Creating a module from a number of files
|
|||
|
|
@cindex Importing files
|
|||
|
|
|
|||
|
|
When you begin using @sc{cvs}, you will probably already have several
|
|||
|
|
projects that can be
|
|||
|
|
put under @sc{cvs} control. In these cases the easiest way is to use the
|
|||
|
|
@code{import} command. An example is probably the easiest way to
|
|||
|
|
explain how to use it. If the files you want to install in
|
|||
|
|
@sc{cvs} reside in @file{@var{dir}}, and you want them to appear in the
|
|||
|
|
repository as @file{$CVSROOT/yoyodyne/@var{dir}}, you can do this:
|
|||
|
|
|
|||
|
|
@example
|
|||
|
|
$ cd @var{dir}
|
|||
|
|
$ cvs import -m "Imported sources" yoyodyne/@var{dir} yoyo start
|
|||
|
|
@end example
|
|||
|
|
|
|||
|
|
Unless you supply a log message with the @samp{-m}
|
|||
|
|
flag, @sc{cvs} starts an editor and prompts for a
|
|||
|
|
message. The string @samp{yoyo} is a @dfn{vendor tag},
|
|||
|
|
and @samp{start} is a @dfn{release tag}. They may fill
|
|||
|
|
no purpose in this context, but since @sc{cvs} requires
|
|||
|
|
them they must be present. @xref{Tracking sources}, for
|
|||
|
|
more information about them.
|
|||
|
|
|
|||
|
|
You can now verify that it worked, and remove your
|
|||
|
|
original source directory.
|
|||
|
|
|
|||
|
|
@example
|
|||
|
|
$ cd ..
|
|||
|
|
$ mv @var{dir} @var{dir}.orig
|
|||
|
|
$ cvs checkout yoyodyne/@var{dir} # @r{Explanation below}
|
|||
|
|
$ ls -R yoyodyne
|
|||
|
|
$ rm -r @var{dir}.orig
|
|||
|
|
@end example
|
|||
|
|
|
|||
|
|
@noindent
|
|||
|
|
Erasing the original sources is a good idea, to make sure that you do
|
|||
|
|
not accidentally edit them in @var{dir}, bypassing @sc{cvs}.
|
|||
|
|
Of course, it would be wise to make sure that you have
|
|||
|
|
a backup of the sources before you remove them.
|
|||
|
|
|
|||
|
|
The @code{checkout} command can either take a module
|
|||
|
|
name as argument (as it has done in all previous
|
|||
|
|
examples) or a path name relative to @code{$CVSROOT},
|
|||
|
|
as it did in the example above.
|
|||
|
|
|
|||
|
|
It is a good idea to check that the permissions
|
|||
|
|
@sc{cvs} sets on the directories inside @samp{$CVSROOT}
|
|||
|
|
are reasonable, and that they belong to the proper
|
|||
|
|
groups. @xref{File permissions}.
|
|||
|
|
|
|||
|
|
@c The node name is too long, but I am having trouble
|
|||
|
|
@c thinking of something more concise.
|
|||
|
|
@node From other version control systems
|
|||
|
|
@subsection Creating Files From Other Version Control Systems
|
|||
|
|
@cindex Importing files, from other version control systesm
|
|||
|
|
|
|||
|
|
If you have a project which you are maintaining with
|
|||
|
|
another version control system, such as @sc{rcs}, you
|
|||
|
|
may wish to put the files from that project into
|
|||
|
|
@sc{cvs}, and preserve the revision history of the
|
|||
|
|
files.
|
|||
|
|
|
|||
|
|
@table @asis
|
|||
|
|
@cindex RCS, importing files from
|
|||
|
|
@item From RCS
|
|||
|
|
If you have been using @sc{rcs}, find the @sc{rcs}
|
|||
|
|
files---usually a file named @file{foo.c} will have its
|
|||
|
|
@sc{rcs} file in @file{RCS/foo.c,v} (but it could be
|
|||
|
|
other places; consult the @sc{rcs} documentation for
|
|||
|
|
details). Then create the appropriate directories in
|
|||
|
|
@sc{cvs} if they do not already exist. Then copy the
|
|||
|
|
files into the appropriate directories in the @sc{cvs}
|
|||
|
|
repository (the name in the repository must be the name
|
|||
|
|
of the source file with @samp{,v} added; the files go
|
|||
|
|
directly in the appopriate directory of the repository,
|
|||
|
|
not in an @file{RCS} subdirectory). This is one of the
|
|||
|
|
few times when it is a good idea to access the @sc{cvs}
|
|||
|
|
repository directly, rather than using @sc{cvs}
|
|||
|
|
commands. Then you are ready to check out a new
|
|||
|
|
working directory.
|
|||
|
|
@c Someday there probably should be a "cvs import -t
|
|||
|
|
@c rcs" or some such. It could even create magic
|
|||
|
|
@c branches. It could also do something about the case
|
|||
|
|
@c where the RCS file had a (non-magic) "0" branch.
|
|||
|
|
|
|||
|
|
@c How many is "many"? Or do they just import RCS files?
|
|||
|
|
@item From another version control system
|
|||
|
|
Many version control systems have the ability to export
|
|||
|
|
@sc{rcs} files in the standard format. If yours does,
|
|||
|
|
export the @sc{rcs} files and then follow the above
|
|||
|
|
instructions.
|
|||
|
|
|
|||
|
|
@cindex SCCS, importing files from
|
|||
|
|
@item From SCCS
|
|||
|
|
There is a script in the @file{contrib} directory of
|
|||
|
|
the @sc{cvs} source distribution called @file{sccs2rcs}
|
|||
|
|
which converts @sc{sccs} files to @sc{rcs} files.
|
|||
|
|
Note: you must run it on a machine which has both
|
|||
|
|
@sc{sccs} and @sc{rcs} installed, and like everything
|
|||
|
|
else in contrib it is unsupported (your mileage may
|
|||
|
|
vary).
|
|||
|
|
@end table
|
|||
|
|
|
|||
|
|
@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
|
|||
|
|
@node From scratch
|
|||
|
|
@subsection Creating a module from scratch
|
|||
|
|
|
|||
|
|
For a new project, the easiest thing to do is probably
|
|||
|
|
to create an empty directory structure, like this:
|
|||
|
|
|
|||
|
|
@example
|
|||
|
|
$ mkdir tc
|
|||
|
|
$ mkdir tc/man
|
|||
|
|
$ mkdir tc/testing
|
|||
|
|
@end example
|
|||
|
|
|
|||
|
|
After that, you use the @code{import} command to create
|
|||
|
|
the corresponding (empty) directory structure inside
|
|||
|
|
the repository:
|
|||
|
|
|
|||
|
|
@example
|
|||
|
|
$ cd tc
|
|||
|
|
$ cvs import -m "Created directory structure" yoyodyne/@var{dir} yoyo start
|
|||
|
|
@end example
|
|||
|
|
|
|||
|
|
Then, use @code{add} to add files (and new directories)
|
|||
|
|
as they appear.
|
|||
|
|
|
|||
|
|
Check that the permissions @sc{cvs} sets on the
|
|||
|
|
directories inside @samp{$CVSROOT} are reasonable.
|
|||
|
|
|
|||
|
|
@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
|
|||
|
|
@node Defining the module
|
|||
|
|
@section Defining the module
|
|||
|
|
@cindex Defining a module
|
|||
|
|
@cindex Editing the modules file
|
|||
|
|
@cindex Module, defining
|
|||
|
|
@cindex Modules file, changing
|
|||
|
|
|
|||
|
|
The next step is to define the module in the
|
|||
|
|
@file{modules} file. This is not strictly necessary,
|
|||
|
|
but modules can be convenient in grouping together
|
|||
|
|
related files and directories.
|
|||
|
|
|
|||
|
|
In simple cases these steps are sufficient to define a module.
|
|||
|
|
|
|||
|
|
@enumerate
|
|||
|
|
@item
|
|||
|
|
Get a working copy of the modules file.
|
|||
|
|
|
|||
|
|
@example
|
|||
|
|
$ cvs checkout modules
|
|||
|
|
$ cd modules
|
|||
|
|
@end example
|
|||
|
|
|
|||
|
|
@item
|
|||
|
|
Edit the file and insert a line that defines the module. @xref{Intro
|
|||
|
|
administrative files}, for an introduction. @xref{modules}, for a full
|
|||
|
|
description of the modules file. You can use the
|
|||
|
|
following line to define the module @samp{tc}:
|
|||
|
|
|
|||
|
|
@example
|
|||
|
|
tc yoyodyne/tc
|
|||
|
|
@end example
|
|||
|
|
|
|||
|
|
@item
|
|||
|
|
Commit your changes to the modules file.
|
|||
|
|
|
|||
|
|
@example
|
|||
|
|
$ cvs commit -m "Added the tc module." modules
|
|||
|
|
@end example
|
|||
|
|
|
|||
|
|
@item
|
|||
|
|
Release the modules module.
|
|||
|
|
|
|||
|
|
@example
|
|||
|
|
$ cd ..
|
|||
|
|
$ cvs release -d modules
|
|||
|
|
@end example
|
|||
|
|
@end enumerate
|
|||
|
|
|
|||
|
|
@c ---------------------------------------------------------------------
|
|||
|
|
@node Multiple developers
|
|||
|
|
@chapter Multiple developers
|
|||
|
|
@cindex Multiple developers
|
|||
|
|
@cindex Team of developers
|
|||
|
|
@cindex File locking
|
|||
|
|
@cindex Locking files
|
|||
|
|
@cindex Working copy
|
|||
|
|
|
|||
|
|
When more than one person works on a software project
|
|||
|
|
things often get complicated. Often, two people try to
|
|||
|
|
edit the same file simultaneously. Some other version
|
|||
|
|
control systems (including @sc{rcs} and @sc{sccs})
|
|||
|
|
try to solve that particular problem by introducing
|
|||
|
|
@dfn{file locking}, so that only one person can edit
|
|||
|
|
each file at a time. Unfortunately, file locking can
|
|||
|
|
be very counter-productive. If two persons want
|
|||
|
|
to edit different parts of a file, there may be no
|
|||
|
|
reason to prevent either of them from doing so.
|
|||
|
|
|
|||
|
|
@sc{cvs} does not use file locking. Instead, it allows many
|
|||
|
|
people to edit their own @dfn{working copy} of a file
|
|||
|
|
simultaneously. The first person that commits his
|
|||
|
|
changes has no automatic way of knowing that another has started to
|
|||
|
|
edit it. Others will get an error message when they
|
|||
|
|
try to commit the file. They must then use @sc{cvs}
|
|||
|
|
commands to bring their working copy up to date with
|
|||
|
|
the repository revision. This process is almost
|
|||
|
|
automatic, and explained in this chapter.
|
|||
|
|
|
|||
|
|
There are many ways to organize a team of developers.
|
|||
|
|
@sc{cvs} does not try to enforce a certain
|
|||
|
|
organization. It is a tool that can be used in several
|
|||
|
|
ways. It is often useful to inform the group of
|
|||
|
|
commits you have done. @sc{cvs} has several ways of
|
|||
|
|
automating that process. @xref{Informing others}.
|
|||
|
|
@xref{Revision management}, for more tips on how to use
|
|||
|
|
@sc{cvs}.
|
|||
|
|
|
|||
|
|
@menu
|
|||
|
|
* File status:: A file can be in several states
|
|||
|
|
* Updating a file:: Bringing a file up-to-date
|
|||
|
|
* Conflicts example:: An informative example
|
|||
|
|
* Informing others:: To cooperate you must inform
|
|||
|
|
* Concurrency:: Simultaneous repository access
|
|||
|
|
* Watches:: Mechanisms to track who is editing files
|
|||
|
|
@end menu
|
|||
|
|
|
|||
|
|
@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
|
|||
|
|
@node File status
|
|||
|
|
@section File status
|
|||
|
|
@cindex File status
|
|||
|
|
@cindex Status of a file
|
|||
|
|
@cindex Four states of a file
|
|||
|
|
|
|||
|
|
After you have checked out a file out from @sc{cvs}, it is in
|
|||
|
|
one of these four states:
|
|||
|
|
|
|||
|
|
@table @asis
|
|||
|
|
@cindex Up-to-date
|
|||
|
|
@item Up-to-date
|
|||
|
|
The file is identical with the latest revision in the
|
|||
|
|
repository.
|
|||
|
|
@c -- The above is not always true if branching is used.
|
|||
|
|
|
|||
|
|
@item Locally modified
|
|||
|
|
@cindex Locally modified
|
|||
|
|
You have edited the file, and not yet committed your changes.
|
|||
|
|
|
|||
|
|
@item Needing update
|
|||
|
|
@cindex Needing update
|
|||
|
|
Someone else has committed a newer revision to the repository.
|
|||
|
|
|
|||
|
|
@item Needing merge
|
|||
|
|
@cindex Needing merge
|
|||
|
|
Someone else have committed a newer revision to the repository, and you
|
|||
|
|
have also made modifications to the file.
|
|||
|
|
@c -- What about "added" "removed" and so on?
|
|||
|
|
@end table
|
|||
|
|
|
|||
|
|
You can use the @code{status} command to find out the status of a given
|
|||
|
|
file. @xref{status}.
|
|||
|
|
|
|||
|
|
@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
|
|||
|
|
@node Updating a file
|
|||
|
|
@section Bringing a file up to date
|
|||
|
|
@cindex Bringing a file up to date
|
|||
|
|
@cindex Updating a file
|
|||
|
|
@cindex Merging a file
|
|||
|
|
@cindex update, introduction
|
|||
|
|
|
|||
|
|
When you want to update or merge a file, use the @code{update}
|
|||
|
|
command. For files that are not up to date this is roughly equivalent
|
|||
|
|
to a @code{checkout} command: the newest revision of the file is
|
|||
|
|
extracted from the repository and put in your working copy of the
|
|||
|
|
module.
|
|||
|
|
|
|||
|
|
Your modifications to a file are never lost when you
|
|||
|
|
use @code{update}. If no newer revision exists,
|
|||
|
|
running @code{update} has no effect. If you have
|
|||
|
|
edited the file, and a newer revision is available,
|
|||
|
|
@sc{cvs} will merge all changes into your working copy.
|
|||
|
|
|
|||
|
|
For instance, imagine that you checked out revision 1.4 and started
|
|||
|
|
editing it. In the meantime someone else committed revision 1.5, and
|
|||
|
|
shortly after that revision 1.6. If you run @code{update} on the file
|
|||
|
|
now, @sc{cvs} will incorporate all changes between revision 1.4 and 1.6 into
|
|||
|
|
your file.
|
|||
|
|
|
|||
|
|
@cindex Overlap
|
|||
|
|
If any of the changes between 1.4 and 1.6 were made too
|
|||
|
|
close to any of the changes you have made, an
|
|||
|
|
@dfn{overlap} occurs. In such cases a warning is
|
|||
|
|
printed, and the resulting file includes both
|
|||
|
|
versions of the lines that overlap, delimited by
|
|||
|
|
special markers.
|
|||
|
|
@xref{update}, for a complete description of the
|
|||
|
|
@code{update} command.
|
|||
|
|
|
|||
|
|
@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
|
|||
|
|
@node Conflicts example
|
|||
|
|
@section Conflicts example
|
|||
|
|
@cindex Merge, an example
|
|||
|
|
@cindex Example of merge
|
|||
|
|
@cindex driver.c (merge example)
|
|||
|
|
|
|||
|
|
Suppose revision 1.4 of @file{driver.c} contains this:
|
|||
|
|
|
|||
|
|
@example
|
|||
|
|
#include <stdio.h>
|
|||
|
|
|
|||
|
|
void main()
|
|||
|
|
@{
|
|||
|
|
parse();
|
|||
|
|
if (nerr == 0)
|
|||
|
|
gencode();
|
|||
|
|
else
|
|||
|
|
fprintf(stderr, "No code generated.\n");
|
|||
|
|
exit(nerr == 0 ? 0 : 1);
|
|||
|
|
@}
|
|||
|
|
@end example
|
|||
|
|
|
|||
|
|
@noindent
|
|||
|
|
Revision 1.6 of @file{driver.c} contains this:
|
|||
|
|
|
|||
|
|
@example
|
|||
|
|
#include <stdio.h>
|
|||
|
|
|
|||
|
|
int main(int argc,
|
|||
|
|
char **argv)
|
|||
|
|
@{
|
|||
|
|
parse();
|
|||
|
|
if (argc != 1)
|
|||
|
|
@{
|
|||
|
|
fprintf(stderr, "tc: No args expected.\n");
|
|||
|
|
exit(1);
|
|||
|
|
@}
|
|||
|
|
if (nerr == 0)
|
|||
|
|
gencode();
|
|||
|
|
else
|
|||
|
|
fprintf(stderr, "No code generated.\n");
|
|||
|
|
exit(!!nerr);
|
|||
|
|
@}
|
|||
|
|
@end example
|
|||
|
|
|
|||
|
|
@noindent
|
|||
|
|
Your working copy of @file{driver.c}, based on revision
|
|||
|
|
1.4, contains this before you run @samp{cvs update}:
|
|||
|
|
@c -- Really include "cvs"?
|
|||
|
|
|
|||
|
|
@example
|
|||
|
|
#include <stdlib.h>
|
|||
|
|
#include <stdio.h>
|
|||
|
|
|
|||
|
|
void main()
|
|||
|
|
@{
|
|||
|
|
init_scanner();
|
|||
|
|
parse();
|
|||
|
|
if (nerr == 0)
|
|||
|
|
gencode();
|
|||
|
|
else
|
|||
|
|
fprintf(stderr, "No code generated.\n");
|
|||
|
|
exit(nerr == 0 ? EXIT_SUCCESS : EXIT_FAILURE);
|
|||
|
|
@}
|
|||
|
|
@end example
|
|||
|
|
|
|||
|
|
@noindent
|
|||
|
|
You run @samp{cvs update}:
|
|||
|
|
@c -- Really include "cvs"?
|
|||
|
|
|
|||
|
|
@example
|
|||
|
|
$ cvs update driver.c
|
|||
|
|
RCS file: /usr/local/cvsroot/yoyodyne/tc/driver.c,v
|
|||
|
|
retrieving revision 1.4
|
|||
|
|
retrieving revision 1.6
|
|||
|
|
Merging differences between 1.4 and 1.6 into driver.c
|
|||
|
|
rcsmerge warning: overlaps during merge
|
|||
|
|
cvs update: conflicts found in driver.c
|
|||
|
|
C driver.c
|
|||
|
|
@end example
|
|||
|
|
|
|||
|
|
@noindent
|
|||
|
|
@cindex Conflicts (merge example)
|
|||
|
|
@sc{cvs} tells you that there were some conflicts.
|
|||
|
|
Your original working file is saved unmodified in
|
|||
|
|
@file{.#driver.c.1.4}. The new version of
|
|||
|
|
@file{driver.c} contains this:
|
|||
|
|
|
|||
|
|
@example
|
|||
|
|
#include <stdlib.h>
|
|||
|
|
#include <stdio.h>
|
|||
|
|
|
|||
|
|
int main(int argc,
|
|||
|
|
char **argv)
|
|||
|
|
@{
|
|||
|
|
init_scanner();
|
|||
|
|
parse();
|
|||
|
|
if (argc != 1)
|
|||
|
|
@{
|
|||
|
|
fprintf(stderr, "tc: No args expected.\n");
|
|||
|
|
exit(1);
|
|||
|
|
@}
|
|||
|
|
if (nerr == 0)
|
|||
|
|
gencode();
|
|||
|
|
else
|
|||
|
|
fprintf(stderr, "No code generated.\n");
|
|||
|
|
<<<<<<< driver.c
|
|||
|
|
exit(nerr == 0 ? EXIT_SUCCESS : EXIT_FAILURE);
|
|||
|
|
=======
|
|||
|
|
exit(!!nerr);
|
|||
|
|
>>>>>>> 1.6
|
|||
|
|
@}
|
|||
|
|
@end example
|
|||
|
|
|
|||
|
|
@noindent
|
|||
|
|
@cindex Markers, conflict
|
|||
|
|
@cindex Conflict markers
|
|||
|
|
@cindex <<<<<<<
|
|||
|
|
@cindex >>>>>>>
|
|||
|
|
@cindex =======
|
|||
|
|
|
|||
|
|
Note how all non-overlapping modifications are incorporated in your working
|
|||
|
|
copy, and that the overlapping section is clearly marked with
|
|||
|
|
@samp{<<<<<<<}, @samp{=======} and @samp{>>>>>>>}.
|
|||
|
|
|
|||
|
|
@cindex Resolving a conflict
|
|||
|
|
@cindex Conflict resolution
|
|||
|
|
You resolve the conflict by editing the file, removing the markers and
|
|||
|
|
the erroneous line. Suppose you end up with this file:
|
|||
|
|
@c -- Add xref to the pcl-cvs manual when it talks
|
|||
|
|
@c -- about this.
|
|||
|
|
@example
|
|||
|
|
#include <stdlib.h>
|
|||
|
|
#include <stdio.h>
|
|||
|
|
|
|||
|
|
int main(int argc,
|
|||
|
|
char **argv)
|
|||
|
|
@{
|
|||
|
|
init_scanner();
|
|||
|
|
parse();
|
|||
|
|
if (argc != 1)
|
|||
|
|
@{
|
|||
|
|
fprintf(stderr, "tc: No args expected.\n");
|
|||
|
|
exit(1);
|
|||
|
|
@}
|
|||
|
|
if (nerr == 0)
|
|||
|
|
gencode();
|
|||
|
|
else
|
|||
|
|
fprintf(stderr, "No code generated.\n");
|
|||
|
|
exit(nerr == 0 ? EXIT_SUCCESS : EXIT_FAILURE);
|
|||
|
|
@}
|
|||
|
|
@end example
|
|||
|
|
|
|||
|
|
@noindent
|
|||
|
|
You can now go ahead and commit this as revision 1.7.
|
|||
|
|
|
|||
|
|
@example
|
|||
|
|
$ cvs commit -m "Initialize scanner. Use symbolic exit values." driver.c
|
|||
|
|
Checking in driver.c;
|
|||
|
|
/usr/local/cvsroot/yoyodyne/tc/driver.c,v <-- driver.c
|
|||
|
|
new revision: 1.7; previous revision: 1.6
|
|||
|
|
done
|
|||
|
|
@end example
|
|||
|
|
|
|||
|
|
@cindex emerge
|
|||
|
|
If you use release 1.04 or later of pcl-cvs (a @sc{gnu}
|
|||
|
|
Emacs front-end for @sc{cvs}) you can use an Emacs
|
|||
|
|
package called emerge to help you resolve conflicts.
|
|||
|
|
See the documentation for pcl-cvs.
|
|||
|
|
|
|||
|
|
@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
|
|||
|
|
@node Informing others
|
|||
|
|
@section Informing others about commits
|
|||
|
|
@cindex Informing others
|
|||
|
|
@cindex Spreading information
|
|||
|
|
@cindex Mail, automatic mail on commit
|
|||
|
|
|
|||
|
|
It is often useful to inform others when you commit a
|
|||
|
|
new revision of a file. The @samp{-i} option of the
|
|||
|
|
@file{modules} file, or the @file{loginfo} file, can be
|
|||
|
|
used to automate this process. @xref{modules}.
|
|||
|
|
@xref{loginfo}. You can use these features of @sc{cvs}
|
|||
|
|
to, for instance, instruct @sc{cvs} to mail a
|
|||
|
|
message to all developers, or post a message to a local
|
|||
|
|
newsgroup.
|
|||
|
|
@c -- More text would be nice here.
|
|||
|
|
|
|||
|
|
@node Concurrency
|
|||
|
|
@section Several developers simultaneously attempting to run CVS
|
|||
|
|
|
|||
|
|
@cindex locks, cvs
|
|||
|
|
If several developers try to run @sc{cvs} at the same
|
|||
|
|
time, one may get the following message:
|
|||
|
|
|
|||
|
|
@example
|
|||
|
|
[11:43:23] waiting for bach's lock in /usr/local/cvsroot/foo
|
|||
|
|
@end example
|
|||
|
|
|
|||
|
|
@sc{cvs} will try again every 30 seconds, and either
|
|||
|
|
continue with the operation or print the message again,
|
|||
|
|
if it still needs to wait. If a lock seems to stick
|
|||
|
|
around for an undue amount of time, find the person
|
|||
|
|
holding the lock and ask them about the cvs command
|
|||
|
|
they are running. If they aren't running a cvs
|
|||
|
|
command, look for and remove files starting with
|
|||
|
|
@file{#cvs.tfl}, @file{#cvs.rfl}, or @file{#cvs.wfl}
|
|||
|
|
from the repository.
|
|||
|
|
|
|||
|
|
Note that these locks are to protect @sc{cvs}'s
|
|||
|
|
internal data structures and have no relationship to
|
|||
|
|
the word @dfn{lock} in the sense used by @sc{rcs}--a
|
|||
|
|
way to prevent other developers from working on a
|
|||
|
|
particular file.
|
|||
|
|
|
|||
|
|
Any number of people can be reading from a given
|
|||
|
|
repository at a time; only when someone is writing do
|
|||
|
|
the locks prevent other people from reading or writing.
|
|||
|
|
|
|||
|
|
@cindex Atomic transactions, lack of
|
|||
|
|
@cindex Transactions, atomic, lack of
|
|||
|
|
One might hope for the following property
|
|||
|
|
|
|||
|
|
@example
|
|||
|
|
If someone commits some changes in one cvs command,
|
|||
|
|
then an update by someone else will either get all the
|
|||
|
|
changes, or none of them.
|
|||
|
|
@end example
|
|||
|
|
|
|||
|
|
but @sc{cvs} does @emph{not} have this property. For
|
|||
|
|
example, given the files
|
|||
|
|
|
|||
|
|
@example
|
|||
|
|
a/one.c
|
|||
|
|
a/two.c
|
|||
|
|
b/three.c
|
|||
|
|
b/four.c
|
|||
|
|
@end example
|
|||
|
|
|
|||
|
|
if someone runs
|
|||
|
|
|
|||
|
|
@example
|
|||
|
|
cvs ci a/two.c b/three.c
|
|||
|
|
@end example
|
|||
|
|
|
|||
|
|
and someone else runs @code{cvs update} at the same
|
|||
|
|
time, the person running @code{update} might get only
|
|||
|
|
the change to @file{b/three.c} and not the change to
|
|||
|
|
@file{a/two.c}.
|
|||
|
|
|
|||
|
|
@node Watches
|
|||
|
|
@section Mechanisms to track who is editing files
|
|||
|
|
@cindex Watches
|
|||
|
|
|
|||
|
|
For many groups, use of @sc{cvs} in its default mode is
|
|||
|
|
perfectly satisfactory. Users may sometimes go to
|
|||
|
|
check in a modification only to find that another
|
|||
|
|
modification has intervened, but they deal with it and
|
|||
|
|
proceed with their check in. Other groups prefer to be
|
|||
|
|
able to know who is editing what files, so that if two
|
|||
|
|
people try to edit the same file they can choose to
|
|||
|
|
talk about who is doing what when rather than be
|
|||
|
|
surprised at check in time. The features in this
|
|||
|
|
section allow such coordination, while retaining the
|
|||
|
|
ability of two developers to edit the same file at the
|
|||
|
|
same time.
|
|||
|
|
|
|||
|
|
For maximum benefit developers should use @code{cvs
|
|||
|
|
edit} (not @code{chmod}) to make files read-write to
|
|||
|
|
edit them, and @code{cvs release} (not @code{rm}) to
|
|||
|
|
discard a working directory which is no longer in use,
|
|||
|
|
but @sc{cvs} is not able to enforce this behavior.
|
|||
|
|
|
|||
|
|
@c I'm a little dissatisfied with this presentation,
|
|||
|
|
@c because "watch on"/"edit"/"editors" are one set of
|
|||
|
|
@c functionality, and "watch add"/"watchers" is another
|
|||
|
|
@c which is somewhat orthogonal even though they interact in
|
|||
|
|
@c various ways. But I think it might be
|
|||
|
|
@c confusing to describe them separately (e.g. "watch
|
|||
|
|
@c add" with loginfo). I don't know.
|
|||
|
|
|
|||
|
|
@menu
|
|||
|
|
* Setting a watch:: Telling CVS to watch certain files
|
|||
|
|
* Getting Notified:: Telling CVS to notify you
|
|||
|
|
* Editing files:: How to edit a file which is being watched
|
|||
|
|
* Watch information:: Information about who is watching and editing
|
|||
|
|
* Watches Compatibility:: Watches interact poorly with CVS 1.6 or earlier
|
|||
|
|
@end menu
|
|||
|
|
|
|||
|
|
@node Setting a watch
|
|||
|
|
@subsection Telling CVS to watch certain files
|
|||
|
|
|
|||
|
|
To enable the watch features, you first specify that
|
|||
|
|
certain files are to be watched.
|
|||
|
|
|
|||
|
|
@cindex watch on (subcommand)
|
|||
|
|
@deffn Command {cvs watch on} [@code{-l}] files @dots{}
|
|||
|
|
|
|||
|
|
Specify that developers should run @code{cvs edit}
|
|||
|
|
before editing @var{files}. CVS will create working
|
|||
|
|
copies of @var{files} read-only, to remind developers
|
|||
|
|
to run the @code{cvs edit} command before working on
|
|||
|
|
them.
|
|||
|
|
|
|||
|
|
If @var{files} includes the name of a directory, CVS
|
|||
|
|
arranges to watch all files added to the corresponding
|
|||
|
|
repository directory, and sets a default for files
|
|||
|
|
added in the future; this allows the user to set
|
|||
|
|
notification policies on a per-directory basis. The
|
|||
|
|
contents of the directory are processed recursively,
|
|||
|
|
unless the @code{-l} option is given.
|
|||
|
|
|
|||
|
|
If @var{files} is omitted, it defaults to the current directory.
|
|||
|
|
|
|||
|
|
@cindex watch off (subcommand)
|
|||
|
|
@end deffn
|
|||
|
|
|
|||
|
|
@deffn Command {cvs watch off} [@code{-l}] files @dots{}
|
|||
|
|
|
|||
|
|
Do not provide notification about work on @var{files}. CVS will create
|
|||
|
|
working copies of @var{files} read-write.
|
|||
|
|
|
|||
|
|
The @var{files} and @code{-l} arguments are processed as for @code{cvs
|
|||
|
|
watch on}.
|
|||
|
|
|
|||
|
|
@end deffn
|
|||
|
|
|
|||
|
|
@node Getting Notified
|
|||
|
|
@subsection Telling CVS to notify you
|
|||
|
|
|
|||
|
|
You can tell @sc{cvs} that you want to receive
|
|||
|
|
notifications about various actions taken on a file.
|
|||
|
|
You can do this without using @code{cvs watch on} for
|
|||
|
|
the file, but generally you will want to use @code{cvs
|
|||
|
|
watch on}, so that developers use the @code{cvs edit}
|
|||
|
|
command.
|
|||
|
|
|
|||
|
|
@cindex watch add (subcommand)
|
|||
|
|
@deffn Command {cvs watch add} [@code{-a} action] [@code{-l}] files @dots{}
|
|||
|
|
|
|||
|
|
Add the current user to the list of people to receive notification of
|
|||
|
|
work done on @var{files}.
|
|||
|
|
|
|||
|
|
The @code{-a} option specifies what kinds of events CVS should notify
|
|||
|
|
the user about. @var{action} is one of the following:
|
|||
|
|
|
|||
|
|
@table @code
|
|||
|
|
|
|||
|
|
@item edit
|
|||
|
|
Another user has applied the @code{cvs edit} command (described
|
|||
|
|
below) to a file.
|
|||
|
|
|
|||
|
|
@item unedit
|
|||
|
|
Another user has applied the @code{cvs unedit} command (described
|
|||
|
|
below) or the @code{cvs release} command to a file, or has deleted
|
|||
|
|
the file and allowed @code{cvs update} to recreate it.
|
|||
|
|
|
|||
|
|
@item commit
|
|||
|
|
Another user has committed changes to a file.
|
|||
|
|
|
|||
|
|
@item all
|
|||
|
|
All of the above.
|
|||
|
|
|
|||
|
|
@item none
|
|||
|
|
None of the above. (This is useful with @code{cvs edit},
|
|||
|
|
described below.)
|
|||
|
|
|
|||
|
|
@end table
|
|||
|
|
|
|||
|
|
The @code{-a} option may appear more than once, or not at all. If
|
|||
|
|
omitted, the action defaults to @code{all}.
|
|||
|
|
|
|||
|
|
The @var{files} and @code{-l} option are processed as for the
|
|||
|
|
@code{cvs watch} commands.
|
|||
|
|
|
|||
|
|
@end deffn
|
|||
|
|
|
|||
|
|
|
|||
|
|
@cindex watch remove (subcommand)
|
|||
|
|
@deffn Command {cvs watch remove} [@code{-a} action] [@code{-l}] files @dots{}
|
|||
|
|
|
|||
|
|
Remove a notification request established using @code{cvs watch add};
|
|||
|
|
the arguments are the same. If the @code{-a} option is present, only
|
|||
|
|
watches for the specified actions are removed.
|
|||
|
|
|
|||
|
|
@end deffn
|
|||
|
|
|
|||
|
|
When the conditions exist for notification, @sc{cvs}
|
|||
|
|
calls the @file{notify} administrative file, passing it
|
|||
|
|
the user to receive the notification and the user who
|
|||
|
|
is taking the action which results in notification.
|
|||
|
|
Normally @file{notify} will just send an email message.
|
|||
|
|
|
|||
|
|
@cindex users (admin file)
|
|||
|
|
Note that if you set this up in the straightforward
|
|||
|
|
way, users receive notifications on the server machine.
|
|||
|
|
One could of course write a @file{notify} script which
|
|||
|
|
directed notifications elsewhere, but to make this
|
|||
|
|
easy, @sc{cvs} allows you to associate a notification
|
|||
|
|
address for each user. To do so create a file
|
|||
|
|
@file{users} in @file{CVSROOT} with a line for each
|
|||
|
|
user in the format @var{user}:@var{value}. Then
|
|||
|
|
instead of passing the name of the user to be notified
|
|||
|
|
to @file{notify}, @sc{cvs} will pass the @var{value}
|
|||
|
|
(normally an email address on some other machine).
|
|||
|
|
|
|||
|
|
@node Editing files
|
|||
|
|
@subsection How to edit a file which is being watched
|
|||
|
|
|
|||
|
|
Since a file which is being watched is checked out
|
|||
|
|
read-only, you cannot simply edit it. To make it
|
|||
|
|
read-write, and inform others that you are planning
|
|||
|
|
to edit it, use the @code{cvs edit} command.
|
|||
|
|
|
|||
|
|
@cindex edit (subcommand)
|
|||
|
|
@deffn Command {cvs edit} [options] files @dots{}
|
|||
|
|
|
|||
|
|
Prepare to edit the working files @var{files}. CVS makes the
|
|||
|
|
@var{files} read-write, and notifies users who have requested
|
|||
|
|
@code{edit} notification for any of @var{files}.
|
|||
|
|
|
|||
|
|
The @code{cvs edit} command accepts the same @var{options} as the
|
|||
|
|
@code{cvs watch add} command, and establishes a temporary watch for the
|
|||
|
|
user on @var{files}; CVS will remove the watch when @var{files} are
|
|||
|
|
@code{unedit}ed or @code{commit}ted. If the user does not wish to
|
|||
|
|
receive notifications, she should specify @code{-a none}.
|
|||
|
|
|
|||
|
|
The @var{files} and @code{-l} option are processed as for the @code{cvs
|
|||
|
|
watch} commands.
|
|||
|
|
|
|||
|
|
@end deffn
|
|||
|
|
|
|||
|
|
Normally when you are done with a set of changes, you
|
|||
|
|
use the @code{cvs commit} command, which checks in your
|
|||
|
|
changes and returns the watched files to their usual
|
|||
|
|
read-only state. But if you instead decide to abandon
|
|||
|
|
your changes, or not to make any changes, you can use
|
|||
|
|
the @code{cvs unedit} command.
|
|||
|
|
|
|||
|
|
@cindex unedit (subcommand)
|
|||
|
|
@deffn Command {cvs unedit} [@code{-l}] files @dots{}
|
|||
|
|
|
|||
|
|
Abandon work on the working files @var{files}, and revert them to the
|
|||
|
|
repository versions on which they are based. CVS makes those
|
|||
|
|
@var{files} read-only for which users have requested notification using
|
|||
|
|
@code{cvs watch on}. CVS notifies users who have requested @code{unedit}
|
|||
|
|
notification for any of @var{files}.
|
|||
|
|
|
|||
|
|
The @var{files} and @code{-l} option are processed as for the
|
|||
|
|
@code{cvs watch} commands.
|
|||
|
|
|
|||
|
|
@end deffn
|
|||
|
|
|
|||
|
|
When using client/server @sc{cvs}, you can use the
|
|||
|
|
@code{cvs edit} and @code{cvs unedit} commands even if
|
|||
|
|
@sc{cvs} is unable to succesfully communicate with the
|
|||
|
|
server; the notifications will be sent upon the next
|
|||
|
|
successful @sc{cvs} command.
|
|||
|
|
|
|||
|
|
@node Watch information
|
|||
|
|
@subsection Information about who is watching and editing
|
|||
|
|
|
|||
|
|
@cindex watchers (subcommand)
|
|||
|
|
@deffn Command {cvs watchers} [@code{-l}] files @dots{}
|
|||
|
|
|
|||
|
|
List the users currently watching changes to @var{files}. The report
|
|||
|
|
includes the files being watched, and the mail address of each watcher.
|
|||
|
|
|
|||
|
|
The @var{files} and @code{-l} arguments are processed as for the
|
|||
|
|
@code{cvs watch} commands.
|
|||
|
|
|
|||
|
|
@end deffn
|
|||
|
|
|
|||
|
|
|
|||
|
|
@cindex editors (subcommand)
|
|||
|
|
@deffn Command {cvs editors} [@code{-l}] files @dots{}
|
|||
|
|
|
|||
|
|
List the users currently working on @var{files}. The report
|
|||
|
|
includes the mail address of each user, the time when the user began
|
|||
|
|
working with the file, and the host and path of the working directory
|
|||
|
|
containing the file.
|
|||
|
|
|
|||
|
|
The @var{files} and @code{-l} arguments are processed as for the
|
|||
|
|
@code{cvs watch} commands.
|
|||
|
|
|
|||
|
|
@end deffn
|
|||
|
|
|
|||
|
|
@node Watches Compatibility
|
|||
|
|
@subsection Using watches with old versions of CVS
|
|||
|
|
|
|||
|
|
@cindex CVS 1.6, and watches
|
|||
|
|
If you use the watch features on a repository, it
|
|||
|
|
creates @file{CVS} directories in the repository and
|
|||
|
|
stores the information about watches in that directory.
|
|||
|
|
If you attempt to use @sc{cvs} 1.6 or earlier with the
|
|||
|
|
repository, you get an error message such as
|
|||
|
|
|
|||
|
|
@example
|
|||
|
|
cvs update: cannot open CVS/Entries for reading: No such file or directory
|
|||
|
|
@end example
|
|||
|
|
|
|||
|
|
and your operation will likely be aborted. To use the
|
|||
|
|
watch features, you must upgrade all copies of @sc{cvs}
|
|||
|
|
which use that repository in local or server mode. If
|
|||
|
|
you cannot upgrade, use the @code{watch off} and
|
|||
|
|
@code{watch remove} commands to remove all watches, and
|
|||
|
|
that will restore the repository to a state which
|
|||
|
|
@sc{cvs} 1.6 can cope with.
|
|||
|
|
|
|||
|
|
@c ---------------------------------------------------------------------
|
|||
|
|
@node Branches
|
|||
|
|
@chapter Branches
|
|||
|
|
@cindex Branches
|
|||
|
|
@cindex Main trunk and branches
|
|||
|
|
@cindex Revision tree, making branches
|
|||
|
|
|
|||
|
|
So far, all revisions shown in this manual have been on
|
|||
|
|
the @dfn{main trunk}
|
|||
|
|
of the revision tree, i.e., all revision numbers
|
|||
|
|
have been of the form @var{x}.@var{y}. One useful
|
|||
|
|
feature, especially when maintaining several releases
|
|||
|
|
of a software product at once, is the ability to make
|
|||
|
|
branches on the revision tree. @dfn{Tags}, symbolic
|
|||
|
|
names for revisions, will also be
|
|||
|
|
introduced in this chapter.
|
|||
|
|
|
|||
|
|
@menu
|
|||
|
|
* Tags:: Tags--Symbolic revisions
|
|||
|
|
* Branches motivation:: What branches are good for
|
|||
|
|
* Creating a branch:: Creating a branch
|
|||
|
|
* Sticky tags:: Sticky tags
|
|||
|
|
@end menu
|
|||
|
|
|
|||
|
|
@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
|
|||
|
|
@node Tags
|
|||
|
|
@section Tags--Symbolic revisions
|
|||
|
|
@cindex Tags
|
|||
|
|
|
|||
|
|
The revision numbers live a life of their own. They
|
|||
|
|
need not have anything at all to do with the release
|
|||
|
|
numbers of your software product. Depending
|
|||
|
|
on how you use @sc{cvs} the revision numbers might change several times
|
|||
|
|
between two releases. As an example, some of the
|
|||
|
|
source files that make up @sc{rcs} 5.6 have the following
|
|||
|
|
revision numbers:
|
|||
|
|
@cindex RCS revision numbers
|
|||
|
|
|
|||
|
|
@example
|
|||
|
|
ci.c 5.21
|
|||
|
|
co.c 5.9
|
|||
|
|
ident.c 5.3
|
|||
|
|
rcs.c 5.12
|
|||
|
|
rcsbase.h 5.11
|
|||
|
|
rcsdiff.c 5.10
|
|||
|
|
rcsedit.c 5.11
|
|||
|
|
rcsfcmp.c 5.9
|
|||
|
|
rcsgen.c 5.10
|
|||
|
|
rcslex.c 5.11
|
|||
|
|
rcsmap.c 5.2
|
|||
|
|
rcsutil.c 5.10
|
|||
|
|
@end example
|
|||
|
|
|
|||
|
|
@cindex tag, command, introduction
|
|||
|
|
@cindex Tag, symbolic name
|
|||
|
|
@cindex Symbolic name (tag)
|
|||
|
|
@cindex Name, symbolic (tag)
|
|||
|
|
You can use the @code{tag} command to give a symbolic name to a
|
|||
|
|
certain revision of a file. You can use the @samp{-v} flag to the
|
|||
|
|
@code{status} command to see all tags that a file has, and
|
|||
|
|
which revision numbers they represent. Tag names can
|
|||
|
|
contain uppercase and lowercase letters, digits,
|
|||
|
|
@samp{-}, and @samp{_}. The two tag names @code{BASE}
|
|||
|
|
and @code{HEAD} are reserved for use by @sc{cvs}. It
|
|||
|
|
is expected that future names which are special to
|
|||
|
|
@sc{cvs} will contain characters such as @samp{%} or
|
|||
|
|
@samp{=}, rather than being named analogously to
|
|||
|
|
@code{BASE} and @code{HEAD}, to avoid conflicts with
|
|||
|
|
actual tag names.
|
|||
|
|
@c FIXME: is the above list of valid characters in tag
|
|||
|
|
@c names complete?
|
|||
|
|
|
|||
|
|
@cindex Adding a tag
|
|||
|
|
@cindex tag, example
|
|||
|
|
The following example shows how you can add a tag to a
|
|||
|
|
file. The commands must be issued inside your working
|
|||
|
|
copy of the module. That is, you should issue the
|
|||
|
|
command in the directory where @file{backend.c}
|
|||
|
|
resides.
|
|||
|
|
|
|||
|
|
@example
|
|||
|
|
$ cvs tag release-0-4 backend.c
|
|||
|
|
T backend.c
|
|||
|
|
$ cvs status -v backend.c
|
|||
|
|
===================================================================
|
|||
|
|
File: backend.c Status: Up-to-date
|
|||
|
|
|
|||
|
|
Version: 1.4 Tue Dec 1 14:39:01 1992
|
|||
|
|
RCS Version: 1.4 /usr/local/cvsroot/yoyodyne/tc/backend.c,v
|
|||
|
|
Sticky Tag: (none)
|
|||
|
|
Sticky Date: (none)
|
|||
|
|
Sticky Options: (none)
|
|||
|
|
|
|||
|
|
Existing Tags:
|
|||
|
|
release-0-4 (revision: 1.4)
|
|||
|
|
|
|||
|
|
@end example
|
|||
|
|
|
|||
|
|
There is seldom reason to tag a file in isolation. A more common use is
|
|||
|
|
to tag all the files that constitute a module with the same tag at
|
|||
|
|
strategic points in the development life-cycle, such as when a release
|
|||
|
|
is made.
|
|||
|
|
|
|||
|
|
@example
|
|||
|
|
$ cvs tag release-1-0 .
|
|||
|
|
cvs tag: Tagging .
|
|||
|
|
T Makefile
|
|||
|
|
T backend.c
|
|||
|
|
T driver.c
|
|||
|
|
T frontend.c
|
|||
|
|
T parser.c
|
|||
|
|
@end example
|
|||
|
|
|
|||
|
|
(When you give @sc{cvs} a directory as argument, it generally applies the
|
|||
|
|
operation to all the files in that directory, and (recursively), to any
|
|||
|
|
subdirectories that it may contain. @xref{Recursive behavior}.)
|
|||
|
|
|
|||
|
|
@cindex Retrieving an old revision using tags
|
|||
|
|
@cindex Tag, retrieving old revisions
|
|||
|
|
The @code{checkout} command has a flag, @samp{-r}, that lets you check out
|
|||
|
|
a certain revision of a module. This flag makes it easy to
|
|||
|
|
retrieve the sources that make up release 1.0 of the module @samp{tc} at
|
|||
|
|
any time in the future:
|
|||
|
|
|
|||
|
|
@example
|
|||
|
|
$ cvs checkout -r release-1-0 tc
|
|||
|
|
@end example
|
|||
|
|
|
|||
|
|
@noindent
|
|||
|
|
This is useful, for instance, if someone claims that there is a bug in
|
|||
|
|
that release, but you cannot find the bug in the current working copy.
|
|||
|
|
|
|||
|
|
You can also check out a module as it was at any given date.
|
|||
|
|
@xref{checkout options}.
|
|||
|
|
|
|||
|
|
When you tag more than one file with the same tag you
|
|||
|
|
can think about the tag as "a curve drawn through a
|
|||
|
|
matrix of filename vs. revision number." Say we have 5
|
|||
|
|
files with the following revisions:
|
|||
|
|
|
|||
|
|
@example
|
|||
|
|
@group
|
|||
|
|
file1 file2 file3 file4 file5
|
|||
|
|
|
|||
|
|
1.1 1.1 1.1 1.1 /--1.1* <-*- TAG
|
|||
|
|
1.2*- 1.2 1.2 -1.2*-
|
|||
|
|
1.3 \- 1.3*- 1.3 / 1.3
|
|||
|
|
1.4 \ 1.4 / 1.4
|
|||
|
|
\-1.5*- 1.5
|
|||
|
|
1.6
|
|||
|
|
@end group
|
|||
|
|
@end example
|
|||
|
|
|
|||
|
|
At some time in the past, the @code{*} versions were tagged.
|
|||
|
|
You can think of the tag as a handle attached to the curve
|
|||
|
|
drawn through the tagged revisions. When you pull on
|
|||
|
|
the handle, you get all the tagged revisions. Another
|
|||
|
|
way to look at it is that you "sight" through a set of
|
|||
|
|
revisions that is "flat" along the tagged revisions,
|
|||
|
|
like this:
|
|||
|
|
|
|||
|
|
@example
|
|||
|
|
@group
|
|||
|
|
file1 file2 file3 file4 file5
|
|||
|
|
|
|||
|
|
1.1
|
|||
|
|
1.2
|
|||
|
|
1.1 1.3 _
|
|||
|
|
1.1 1.2 1.4 1.1 /
|
|||
|
|
1.2*----1.3*----1.5*----1.2*----1.1 (--- <--- Look here
|
|||
|
|
1.3 1.6 1.3 \_
|
|||
|
|
1.4 1.4
|
|||
|
|
1.5
|
|||
|
|
@end group
|
|||
|
|
@end example
|
|||
|
|
|
|||
|
|
@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
|
|||
|
|
@node Branches motivation
|
|||
|
|
@section What branches are good for
|
|||
|
|
@cindex Branches motivation
|
|||
|
|
@cindex What branches are good for
|
|||
|
|
@cindex Motivation for branches
|
|||
|
|
|
|||
|
|
Suppose that release 1.0 of tc has been made. You are continuing to
|
|||
|
|
develop tc, planning to create release 1.1 in a couple of months. After a
|
|||
|
|
while your customers start to complain about a fatal bug. You check
|
|||
|
|
out release 1.0 (@pxref{Tags}) and find the bug
|
|||
|
|
(which turns out to have a trivial fix). However, the current revision
|
|||
|
|
of the sources are in a state of flux and are not expected to be stable
|
|||
|
|
for at least another month. There is no way to make a
|
|||
|
|
bugfix release based on the newest sources.
|
|||
|
|
|
|||
|
|
The thing to do in a situation like this is to create a @dfn{branch} on
|
|||
|
|
the revision trees for all the files that make up
|
|||
|
|
release 1.0 of tc. You can then make
|
|||
|
|
modifications to the branch without disturbing the main trunk. When the
|
|||
|
|
modifications are finished you can select to either incorporate them on
|
|||
|
|
the main trunk, or leave them on the branch.
|
|||
|
|
|
|||
|
|
@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
|
|||
|
|
@node Creating a branch
|
|||
|
|
@section Creating a branch
|
|||
|
|
@cindex Creating a branch
|
|||
|
|
@cindex Branch, creating a
|
|||
|
|
@cindex rtag, creating a branch using
|
|||
|
|
|
|||
|
|
@c FIXME: should be more explicit about the value of
|
|||
|
|
@c having a tag on the branchpoint. Also should talk
|
|||
|
|
@c about creating a branch with tag not rtag.
|
|||
|
|
The @code{rtag} command can be used to create a branch.
|
|||
|
|
The @code{rtag} command is much like @code{tag}, but it
|
|||
|
|
does not require that you have a working copy of the
|
|||
|
|
module. @xref{rtag}. (You can also use the @code{tag}
|
|||
|
|
command; @pxref{tag}).
|
|||
|
|
|
|||
|
|
@example
|
|||
|
|
$ cvs rtag -b -r release-1-0 release-1-0-patches tc
|
|||
|
|
@end example
|
|||
|
|
|
|||
|
|
The @samp{-b} flag makes @code{rtag} create a branch
|
|||
|
|
(rather than just a symbolic revision name). @samp{-r
|
|||
|
|
release-1-0} says that this branch should be rooted at the node (in
|
|||
|
|
the revision tree) that corresponds to the tag
|
|||
|
|
@samp{release-1-0}. Note that the numeric revision number that matches
|
|||
|
|
@samp{release-1-0} will probably be different from file to file. The
|
|||
|
|
name of the new branch is @samp{release-1-0-patches}, and the
|
|||
|
|
module affected is @samp{tc}.
|
|||
|
|
|
|||
|
|
To fix the problem in release 1.0, you need a working
|
|||
|
|
copy of the branch you just created.
|
|||
|
|
|
|||
|
|
@example
|
|||
|
|
$ cvs checkout -r release-1-0-patches tc
|
|||
|
|
$ cvs status -v driver.c backend.c
|
|||
|
|
===================================================================
|
|||
|
|
File: driver.c Status: Up-to-date
|
|||
|
|
|
|||
|
|
Version: 1.7 Sat Dec 5 18:25:54 1992
|
|||
|
|
RCS Version: 1.7 /usr/local/cvsroot/yoyodyne/tc/driver.c,v
|
|||
|
|
Sticky Tag: release-1-0-patches (branch: 1.7.2)
|
|||
|
|
Sticky Date: (none)
|
|||
|
|
Sticky Options: (none)
|
|||
|
|
|
|||
|
|
Existing Tags:
|
|||
|
|
release-1-0-patches (branch: 1.7.2)
|
|||
|
|
release-1-0 (revision: 1.7)
|
|||
|
|
|
|||
|
|
===================================================================
|
|||
|
|
File: backend.c Status: Up-to-date
|
|||
|
|
|
|||
|
|
Version: 1.4 Tue Dec 1 14:39:01 1992
|
|||
|
|
RCS Version: 1.4 /usr/local/cvsroot/yoyodyne/tc/backend.c,v
|
|||
|
|
Sticky Tag: release-1-0-patches (branch: 1.4.2)
|
|||
|
|
Sticky Date: (none)
|
|||
|
|
Sticky Options: (none)
|
|||
|
|
|
|||
|
|
Existing Tags:
|
|||
|
|
release-1-0-patches (branch: 1.4.2)
|
|||
|
|
release-1-0 (revision: 1.4)
|
|||
|
|
release-0-4 (revision: 1.4)
|
|||
|
|
|
|||
|
|
@end example
|
|||
|
|
|
|||
|
|
@cindex Branch numbers
|
|||
|
|
As the output from the @code{status} command shows the branch
|
|||
|
|
number is created by adding a digit at the tail of the revision number
|
|||
|
|
it is based on. (If @samp{release-1-0} corresponds to revision 1.4, the
|
|||
|
|
branch's revision number will be 1.4.2. For obscure reasons @sc{cvs} always
|
|||
|
|
gives branches even numbers, starting at 2.
|
|||
|
|
@xref{Revision numbers}).
|
|||
|
|
|
|||
|
|
@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
|
|||
|
|
@node Sticky tags
|
|||
|
|
@section Sticky tags
|
|||
|
|
@cindex Sticky tags
|
|||
|
|
@cindex Tags, sticky
|
|||
|
|
@cindex Branches, sticky
|
|||
|
|
|
|||
|
|
@c FIXME: make this stand alone better; many places
|
|||
|
|
@c @xref to this node.
|
|||
|
|
The @samp{-r release-1-0-patches} flag that was given
|
|||
|
|
to @code{checkout} in the previous example
|
|||
|
|
is @dfn{sticky}, that is, it will apply to subsequent commands
|
|||
|
|
in this directory. If you commit any modifications, they are
|
|||
|
|
committed on the branch. You can later merge the modifications into
|
|||
|
|
the main trunk. @xref{Merging}.
|
|||
|
|
|
|||
|
|
You can use the @code{status} command to see what
|
|||
|
|
sticky tags or dates are set:
|
|||
|
|
|
|||
|
|
@c FIXME: This example needs to stand alone better and it
|
|||
|
|
@c would also better if it didn't use -v which only
|
|||
|
|
@c clutters the output in this context.
|
|||
|
|
@example
|
|||
|
|
$ vi driver.c # @r{Fix the bugs}
|
|||
|
|
$ cvs commit -m "Fixed initialization bug" driver.c
|
|||
|
|
Checking in driver.c;
|
|||
|
|
/usr/local/cvsroot/yoyodyne/tc/driver.c,v <-- driver.c
|
|||
|
|
new revision: 1.7.2.1; previous revision: 1.7
|
|||
|
|
done
|
|||
|
|
$ cvs status -v driver.c
|
|||
|
|
===================================================================
|
|||
|
|
File: driver.c Status: Up-to-date
|
|||
|
|
|
|||
|
|
Version: 1.7.2.1 Sat Dec 5 19:35:03 1992
|
|||
|
|
RCS Version: 1.7.2.1 /usr/local/cvsroot/yoyodyne/tc/driver.c,v
|
|||
|
|
Sticky Tag: release-1-0-patches (branch: 1.7.2)
|
|||
|
|
Sticky Date: (none)
|
|||
|
|
Sticky Options: (none)
|
|||
|
|
|
|||
|
|
Existing Tags:
|
|||
|
|
release-1-0-patches (branch: 1.7.2)
|
|||
|
|
release-1-0 (revision: 1.7)
|
|||
|
|
|
|||
|
|
@end example
|
|||
|
|
|
|||
|
|
@cindex Resetting sticky tags
|
|||
|
|
@cindex Sticky tags, resetting
|
|||
|
|
@cindex Deleting sticky tags
|
|||
|
|
The sticky tags will remain on your working files until
|
|||
|
|
you delete them with @samp{cvs update -A}. The
|
|||
|
|
@samp{-A} option retrieves the version of the file from
|
|||
|
|
the head of the trunk, and forgets any sticky tags,
|
|||
|
|
dates, or options.
|
|||
|
|
|
|||
|
|
@c Is the fact that CVS works this way a bug or a
|
|||
|
|
@c feature? If a feature, describe how you would use
|
|||
|
|
@c it to do something useful.
|
|||
|
|
Sticky tags are not just for branches. If you check
|
|||
|
|
out a certain revision (such as 1.4) it will also
|
|||
|
|
become sticky. Subsequent @samp{cvs update} will not
|
|||
|
|
retrieve the latest revision until you reset the tag
|
|||
|
|
with @samp{cvs update -A}. Likewise, use of the
|
|||
|
|
@samp{-D} option to @code{update} or @code{checkout}
|
|||
|
|
sets a @dfn{sticky date}, which, similarly, causes that
|
|||
|
|
date to be used for future retrievals.
|
|||
|
|
|
|||
|
|
@cindex Restoring old version of removed file
|
|||
|
|
@cindex Resurrecting old version of dead file
|
|||
|
|
Many times you will want to retrieve an old version of
|
|||
|
|
a file without setting a sticky tag. The way to do
|
|||
|
|
that is with the @samp{-p} option to @code{checkout} or
|
|||
|
|
@code{update}, which sends the contents of the file to
|
|||
|
|
standard output. For example, suppose you have a file
|
|||
|
|
named @file{file1} which existed as revision 1.1, and
|
|||
|
|
you then removed it (thus adding a dead revision 1.2).
|
|||
|
|
Now suppose you want to add it again, with the same
|
|||
|
|
contents it had previously. Here is how to do it:
|
|||
|
|
|
|||
|
|
@example
|
|||
|
|
$ cvs update -p -r 1.1 file1 >file1
|
|||
|
|
===================================================================
|
|||
|
|
Checking out file1
|
|||
|
|
RCS: /tmp/cvs-sanity/cvsroot/first-dir/Attic/file1,v
|
|||
|
|
VERS: 1.1
|
|||
|
|
***************
|
|||
|
|
$ cvs add file1
|
|||
|
|
cvs add: version 1.2 of `file1' will be resurrected
|
|||
|
|
cvs add: use 'cvs commit' to add this file permanently
|
|||
|
|
$ cvs commit -m test
|
|||
|
|
Checking in file1;
|
|||
|
|
/tmp/cvs-sanity/cvsroot/first-dir/file1,v <-- file1
|
|||
|
|
new revision: 1.3; previous revision: 1.2
|
|||
|
|
done
|
|||
|
|
$
|
|||
|
|
@end example
|
|||
|
|
|
|||
|
|
@c ---------------------------------------------------------------------
|
|||
|
|
@node Merging
|
|||
|
|
@chapter Merging
|
|||
|
|
@cindex Merging
|
|||
|
|
@cindex Copying changes
|
|||
|
|
@cindex Branches, copying changes between
|
|||
|
|
@cindex Changes, copying between branches
|
|||
|
|
@cindex Modifications, copying between branches
|
|||
|
|
|
|||
|
|
You can include the changes made between any two
|
|||
|
|
revisions into your working copy, by @dfn{merging}.
|
|||
|
|
You can then commit that revision, and thus effectively
|
|||
|
|
copy the changes onto another branch.
|
|||
|
|
|
|||
|
|
@menu
|
|||
|
|
* Merging a branch:: Merging an entire branch
|
|||
|
|
* Merging more than once:: Merging from a branch several times
|
|||
|
|
* Merging two revisions:: Merging differences between two revisions
|
|||
|
|
@end menu
|
|||
|
|
|
|||
|
|
@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
|
|||
|
|
@node Merging a branch
|
|||
|
|
@section Merging an entire branch
|
|||
|
|
@cindex Merging a branch
|
|||
|
|
@cindex -j (merging branches)
|
|||
|
|
|
|||
|
|
You can merge changes made on a branch into your working copy by giving
|
|||
|
|
the @samp{-j @var{branch}} flag to the @code{update} command. With one
|
|||
|
|
@samp{-j @var{branch}} option it merges the changes made between the
|
|||
|
|
point where the branch forked and newest revision on that branch (into
|
|||
|
|
your working copy).
|
|||
|
|
|
|||
|
|
@cindex Join
|
|||
|
|
The @samp{-j} stands for ``join''.
|
|||
|
|
|
|||
|
|
@cindex Branch merge example
|
|||
|
|
@cindex Example, branch merge
|
|||
|
|
@cindex Merge, branch example
|
|||
|
|
Consider this revision tree:
|
|||
|
|
|
|||
|
|
@example
|
|||
|
|
+-----+ +-----+ +-----+ +-----+
|
|||
|
|
! 1.1 !----! 1.2 !----! 1.3 !----! 1.4 ! <- The main trunk
|
|||
|
|
+-----+ +-----+ +-----+ +-----+
|
|||
|
|
!
|
|||
|
|
!
|
|||
|
|
! +---------+ +---------+
|
|||
|
|
Branch R1fix -> +---! 1.2.2.1 !----! 1.2.2.2 !
|
|||
|
|
+---------+ +---------+
|
|||
|
|
@end example
|
|||
|
|
|
|||
|
|
@noindent
|
|||
|
|
The branch 1.2.2 has been given the tag (symbolic name) @samp{R1fix}. The
|
|||
|
|
following example assumes that the module @samp{mod} contains only one
|
|||
|
|
file, @file{m.c}.
|
|||
|
|
|
|||
|
|
@example
|
|||
|
|
$ cvs checkout mod # @r{Retrieve the latest revision, 1.4}
|
|||
|
|
|
|||
|
|
$ cvs update -j R1fix m.c # @r{Merge all changes made on the branch,}
|
|||
|
|
# @r{i.e. the changes between revision 1.2}
|
|||
|
|
# @r{and 1.2.2.2, into your working copy}
|
|||
|
|
# @r{of the file.}
|
|||
|
|
|
|||
|
|
$ cvs commit -m "Included R1fix" # @r{Create revision 1.5.}
|
|||
|
|
@end example
|
|||
|
|
|
|||
|
|
A conflict can result from a merge operation. If that
|
|||
|
|
happens, you should resolve it before committing the
|
|||
|
|
new revision. @xref{Conflicts example}.
|
|||
|
|
|
|||
|
|
The @code{checkout} command also supports the @samp{-j @var{branch}} flag. The
|
|||
|
|
same effect as above could be achieved with this:
|
|||
|
|
|
|||
|
|
@example
|
|||
|
|
$ cvs checkout -j R1fix mod
|
|||
|
|
$ cvs commit -m "Included R1fix"
|
|||
|
|
@end example
|
|||
|
|
|
|||
|
|
@node Merging more than once
|
|||
|
|
@section Merging from a branch several times
|
|||
|
|
|
|||
|
|
Continuing our example, the revision tree now looks
|
|||
|
|
like this:
|
|||
|
|
|
|||
|
|
@example
|
|||
|
|
+-----+ +-----+ +-----+ +-----+ +-----+
|
|||
|
|
! 1.1 !----! 1.2 !----! 1.3 !----! 1.4 !----! 1.5 ! <- The main trunk
|
|||
|
|
+-----+ +-----+ +-----+ +-----+ +-----+
|
|||
|
|
! *
|
|||
|
|
! *
|
|||
|
|
! +---------+ +---------+
|
|||
|
|
Branch R1fix -> +---! 1.2.2.1 !----! 1.2.2.2 !
|
|||
|
|
+---------+ +---------+
|
|||
|
|
@end example
|
|||
|
|
|
|||
|
|
where the starred line represents the merge from the
|
|||
|
|
@samp{R1fix} branch to the main trunk, as just
|
|||
|
|
discussed.
|
|||
|
|
|
|||
|
|
Now suppose that development continues on the
|
|||
|
|
@samp{R1fix} branch:
|
|||
|
|
|
|||
|
|
@example
|
|||
|
|
+-----+ +-----+ +-----+ +-----+ +-----+
|
|||
|
|
! 1.1 !----! 1.2 !----! 1.3 !----! 1.4 !----! 1.5 ! <- The main trunk
|
|||
|
|
+-----+ +-----+ +-----+ +-----+ +-----+
|
|||
|
|
! *
|
|||
|
|
! *
|
|||
|
|
! +---------+ +---------+ +---------+
|
|||
|
|
Branch R1fix -> +---! 1.2.2.1 !----! 1.2.2.2 !----! 1.2.2.3 !
|
|||
|
|
+---------+ +---------+ +---------+
|
|||
|
|
@end example
|
|||
|
|
|
|||
|
|
and then you want to merge those new changes onto the
|
|||
|
|
main trunk. If you just use the @code{cvs update -j
|
|||
|
|
R1fix m.c} command again, @sc{cvs} will attempt to
|
|||
|
|
merge again the changes which you have already merged,
|
|||
|
|
which can have undesirable side effects.
|
|||
|
|
|
|||
|
|
So instead you need to specify that you only want to
|
|||
|
|
merge the changes on the branch which have not yet been
|
|||
|
|
merged into the trunk. To do that you specify two
|
|||
|
|
@samp{-j} options, and @sc{cvs} merges the changes from
|
|||
|
|
the first revision to the second revision. For
|
|||
|
|
example, in this case the simplest way would be
|
|||
|
|
|
|||
|
|
@example
|
|||
|
|
cvs update -j 1.2.2.2 -j R1fix m.c # @r{Merge changes from 1.2.2.2 to the}
|
|||
|
|
# @r{head of the R1fix branch}
|
|||
|
|
@end example
|
|||
|
|
|
|||
|
|
The problem with this is that you need to specify the
|
|||
|
|
1.2.2.2 revision manually. A slightly better approach
|
|||
|
|
might be to use the date the last merge was done:
|
|||
|
|
|
|||
|
|
@example
|
|||
|
|
cvs update -j R1fix:yesterday -j R1fix m.c
|
|||
|
|
@end example
|
|||
|
|
|
|||
|
|
Better yet, tag the R1fix branch after every merge into
|
|||
|
|
the trunk, and then use that tag for subsequent merges:
|
|||
|
|
|
|||
|
|
@example
|
|||
|
|
cvs update -j merged_from_R1fix_to_trunk -j R1fix m.c
|
|||
|
|
@end example
|
|||
|
|
|
|||
|
|
@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
|
|||
|
|
@node Merging two revisions
|
|||
|
|
@section Merging differences between any two revisions
|
|||
|
|
@cindex Merging two revisions
|
|||
|
|
@cindex Revisions, merging differences between
|
|||
|
|
@cindex Differences, merging
|
|||
|
|
|
|||
|
|
With two @samp{-j @var{revision}} flags, the @code{update}
|
|||
|
|
(and @code{checkout}) command can merge the differences
|
|||
|
|
between any two revisions into your working file.
|
|||
|
|
|
|||
|
|
@cindex Undoing a change
|
|||
|
|
@cindex Removing a change
|
|||
|
|
@example
|
|||
|
|
$ cvs update -j 1.5 -j 1.3 backend.c
|
|||
|
|
@end example
|
|||
|
|
|
|||
|
|
@noindent
|
|||
|
|
will @emph{remove} all changes made between revision
|
|||
|
|
1.3 and 1.5. Note the order of the revisions!
|
|||
|
|
|
|||
|
|
If you try to use this option when operating on
|
|||
|
|
multiple files, remember that the numeric revisions will
|
|||
|
|
probably be very different between the various files
|
|||
|
|
that make up a module. You almost always use symbolic
|
|||
|
|
tags rather than revision numbers when operating on
|
|||
|
|
multiple files.
|
|||
|
|
|
|||
|
|
@c ---------------------------------------------------------------------
|
|||
|
|
@node Recursive behavior
|
|||
|
|
@chapter Recursive behavior
|
|||
|
|
@cindex Recursive (directory descending)
|
|||
|
|
@cindex Directory, descending
|
|||
|
|
@cindex Descending directories
|
|||
|
|
@cindex Subdirectories
|
|||
|
|
|
|||
|
|
Almost all of the subcommands of @sc{cvs} work
|
|||
|
|
recursively when you specify a directory as an
|
|||
|
|
argument. For instance, consider this directory
|
|||
|
|
structure:
|
|||
|
|
|
|||
|
|
@example
|
|||
|
|
@code{$HOME}
|
|||
|
|
|
|
|||
|
|
+--@t{tc}
|
|||
|
|
| |
|
|||
|
|
+--@t{CVS}
|
|||
|
|
| (internal @sc{cvs} files)
|
|||
|
|
+--@t{Makefile}
|
|||
|
|
+--@t{backend.c}
|
|||
|
|
+--@t{driver.c}
|
|||
|
|
+--@t{frontend.c}
|
|||
|
|
+--@t{parser.c}
|
|||
|
|
+--@t{man}
|
|||
|
|
| |
|
|||
|
|
| +--@t{CVS}
|
|||
|
|
| | (internal @sc{cvs} files)
|
|||
|
|
| +--@t{tc.1}
|
|||
|
|
|
|
|||
|
|
+--@t{testing}
|
|||
|
|
|
|
|||
|
|
+--@t{CVS}
|
|||
|
|
| (internal @sc{cvs} files)
|
|||
|
|
+--@t{testpgm.t}
|
|||
|
|
+--@t{test2.t}
|
|||
|
|
@end example
|
|||
|
|
|
|||
|
|
@noindent
|
|||
|
|
If @file{tc} is the current working directory, the
|
|||
|
|
following is true:
|
|||
|
|
|
|||
|
|
@itemize @bullet
|
|||
|
|
@item
|
|||
|
|
@samp{cvs update testing} is equivalent to @samp{cvs
|
|||
|
|
update testing/testpgm.t testing/test2.t}
|
|||
|
|
|
|||
|
|
@item
|
|||
|
|
@samp{cvs update testing man} updates all files in the
|
|||
|
|
subdirectories
|
|||
|
|
|
|||
|
|
@item
|
|||
|
|
@samp{cvs update .} or just @samp{cvs update} updates
|
|||
|
|
all files in the @code{tc} module
|
|||
|
|
@end itemize
|
|||
|
|
|
|||
|
|
If no arguments are given to @code{update} it will
|
|||
|
|
update all files in the current working directory and
|
|||
|
|
all its subdirectories. In other words, @file{.} is a
|
|||
|
|
default argument to @code{update}. This is also true
|
|||
|
|
for most of the @sc{cvs} subcommands, not only the
|
|||
|
|
@code{update} command.
|
|||
|
|
|
|||
|
|
The recursive behavior of the @sc{cvs} subcommands can be
|
|||
|
|
turned off with the @samp{-l} option.
|
|||
|
|
|
|||
|
|
@example
|
|||
|
|
$ cvs update -l # @r{Don't update files in subdirectories}
|
|||
|
|
@end example
|
|||
|
|
|
|||
|
|
@c ---------------------------------------------------------------------
|
|||
|
|
@node Adding files
|
|||
|
|
@chapter Adding files to a module
|
|||
|
|
@cindex Adding files
|
|||
|
|
|
|||
|
|
To add a new file to a module, follow these steps.
|
|||
|
|
|
|||
|
|
@itemize @bullet
|
|||
|
|
@item
|
|||
|
|
You must have a working copy of the module.
|
|||
|
|
@xref{Getting the source}.
|
|||
|
|
|
|||
|
|
@item
|
|||
|
|
Create the new file inside your working copy of the module.
|
|||
|
|
|
|||
|
|
@item
|
|||
|
|
Use @samp{cvs add @var{filename}} to tell @sc{cvs} that you
|
|||
|
|
want to version control the file.
|
|||
|
|
|
|||
|
|
@item
|
|||
|
|
Use @samp{cvs commit @var{filename}} to actually check
|
|||
|
|
in the file into the repository. Other developers
|
|||
|
|
cannot see the file until you perform this step.
|
|||
|
|
|
|||
|
|
@item
|
|||
|
|
If the file contains binary data it might be necessary
|
|||
|
|
to change the default keyword substitution.
|
|||
|
|
@xref{Keyword substitution}. @xref{admin examples}.
|
|||
|
|
@end itemize
|
|||
|
|
|
|||
|
|
You can also use the @code{add} command to add a new
|
|||
|
|
directory inside a module.
|
|||
|
|
|
|||
|
|
Unlike most other commands, the @code{add} command is
|
|||
|
|
not recursive. You cannot even type @samp{cvs add
|
|||
|
|
foo/bar}! Instead, you have to
|
|||
|
|
|
|||
|
|
@example
|
|||
|
|
$ cd foo
|
|||
|
|
$ cvs add bar
|
|||
|
|
@end example
|
|||
|
|
|
|||
|
|
@xref{add}, for a more complete description of the @code{add}
|
|||
|
|
command.
|
|||
|
|
|
|||
|
|
@c ---------------------------------------------------------------------
|
|||
|
|
@node Removing files
|
|||
|
|
@chapter Removing files from a module
|
|||
|
|
@cindex Removing files
|
|||
|
|
@cindex Deleting files
|
|||
|
|
|
|||
|
|
Modules change. New files are added, and old files
|
|||
|
|
disappear. Still, you want to be able to retrieve an
|
|||
|
|
exact copy of old releases of the module.
|
|||
|
|
|
|||
|
|
Here is what you can do to remove a file from a module,
|
|||
|
|
but remain able to retrieve old revisions:
|
|||
|
|
|
|||
|
|
@itemize @bullet
|
|||
|
|
@item
|
|||
|
|
Make sure that you have not made any uncommitted
|
|||
|
|
modifications to the file. @xref{Viewing differences},
|
|||
|
|
for one way to do that. You can also use the
|
|||
|
|
@code{status} or @code{update} command. If you remove
|
|||
|
|
the file without committing your changes, you will of
|
|||
|
|
course not be able to retrieve the file as it was
|
|||
|
|
immediately before you deleted it.
|
|||
|
|
|
|||
|
|
@item
|
|||
|
|
Remove the file from your working copy of the module.
|
|||
|
|
You can for instance use @code{rm}.
|
|||
|
|
|
|||
|
|
@item
|
|||
|
|
Use @samp{cvs remove @var{filename}} to tell @sc{cvs} that
|
|||
|
|
you really want to delete the file.
|
|||
|
|
|
|||
|
|
@item
|
|||
|
|
Use @samp{cvs commit @var{filename}} to actually
|
|||
|
|
perform the removal of the file from the repository.
|
|||
|
|
@end itemize
|
|||
|
|
|
|||
|
|
When you commit the removal of the file, @sc{cvs}
|
|||
|
|
records the fact that the file no longer exists. It is
|
|||
|
|
possible for a file to exist on only some branches and
|
|||
|
|
not on others, or to re-add another file with the same
|
|||
|
|
name later. CVS will correctly create or not create
|
|||
|
|
the file, based on the @samp{-r} and @samp{-D} options
|
|||
|
|
specified to @code{checkout} or @code{update}.
|
|||
|
|
|
|||
|
|
@cindex Remove (subcommand)
|
|||
|
|
@deffn Command {cvs remove} [@code{-lR}] files @dots{}
|
|||
|
|
|
|||
|
|
Schedule file(s) to be removed from the repository
|
|||
|
|
(files which have not already been removed from the
|
|||
|
|
working directory are not processed). This command
|
|||
|
|
does not actually remove the file from the repository
|
|||
|
|
until you commit the removal. The @samp{-R} option
|
|||
|
|
(the default) specifies that it will recurse into
|
|||
|
|
subdirectories; @samp{-l} specifies that it will not.
|
|||
|
|
@end deffn
|
|||
|
|
|
|||
|
|
Here is an example of removing several files:
|
|||
|
|
|
|||
|
|
@example
|
|||
|
|
$ cd test
|
|||
|
|
$ rm ?.c
|
|||
|
|
$ cvs remove
|
|||
|
|
cvs remove: Removing .
|
|||
|
|
cvs remove: scheduling a.c for removal
|
|||
|
|
cvs remove: scheduling b.c for removal
|
|||
|
|
cvs remove: use 'cvs commit' to remove these files permanently
|
|||
|
|
$ cvs ci -m "Removed unneeded files"
|
|||
|
|
cvs commit: Examining .
|
|||
|
|
cvs commit: Committing .
|
|||
|
|
@end example
|
|||
|
|
|
|||
|
|
If you change your mind you can easily resurrect the
|
|||
|
|
file before you commit it, using the @code{add}
|
|||
|
|
command.
|
|||
|
|
|
|||
|
|
@example
|
|||
|
|
$ ls
|
|||
|
|
CVS ja.h oj.c
|
|||
|
|
$ rm oj.c
|
|||
|
|
$ cvs remove oj.c
|
|||
|
|
cvs remove: scheduling oj.c for removal
|
|||
|
|
cvs remove: use 'cvs commit' to remove this file permanently
|
|||
|
|
$ cvs add oj.c
|
|||
|
|
U oj.c
|
|||
|
|
cvs add: oj.c, version 1.1.1.1, resurrected
|
|||
|
|
@end example
|
|||
|
|
|
|||
|
|
If you realize your mistake before you run the
|
|||
|
|
@code{remove} command you can use @code{update} to
|
|||
|
|
resurrect the file:
|
|||
|
|
|
|||
|
|
@example
|
|||
|
|
$ rm oj.c
|
|||
|
|
$ cvs update oj.c
|
|||
|
|
cvs update: warning: oj.c was lost
|
|||
|
|
U oj.c
|
|||
|
|
@end example
|
|||
|
|
|
|||
|
|
@c ---------------------------------------------------------------------
|
|||
|
|
@node Tracking sources
|
|||
|
|
@chapter Tracking third-party sources
|
|||
|
|
@cindex Third-party sources
|
|||
|
|
@cindex Tracking sources
|
|||
|
|
|
|||
|
|
If you modify a program to better fit your site, you
|
|||
|
|
probably want to include your modifications when the next
|
|||
|
|
release of the program arrives. @sc{cvs} can help you with
|
|||
|
|
this task.
|
|||
|
|
|
|||
|
|
@cindex Vendor
|
|||
|
|
@cindex Vendor branch
|
|||
|
|
@cindex Branch, vendor-
|
|||
|
|
In the terminology used in @sc{cvs}, the supplier of the
|
|||
|
|
program is called a @dfn{vendor}. The unmodified
|
|||
|
|
distribution from the vendor is checked in on its own
|
|||
|
|
branch, the @dfn{vendor branch}. @sc{cvs} reserves branch
|
|||
|
|
1.1.1 for this use.
|
|||
|
|
|
|||
|
|
When you modify the source and commit it, your revision
|
|||
|
|
will end up on the main trunk. When a new release is
|
|||
|
|
made by the vendor, you commit it on the vendor branch
|
|||
|
|
and copy the modifications onto the main trunk.
|
|||
|
|
|
|||
|
|
Use the @code{import} command to create and update
|
|||
|
|
the vendor branch. After a successful @code{import}
|
|||
|
|
the vendor branch is made the `head' revision, so
|
|||
|
|
anyone that checks out a copy of the file gets that
|
|||
|
|
revision. When a local modification is committed it is
|
|||
|
|
placed on the main trunk, and made the `head'
|
|||
|
|
revision.
|
|||
|
|
|
|||
|
|
@menu
|
|||
|
|
* First import:: Importing a module for the first time
|
|||
|
|
* Update imports:: Updating a module with the import command
|
|||
|
|
@end menu
|
|||
|
|
|
|||
|
|
@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
|
|||
|
|
@node First import
|
|||
|
|
@section Importing a module for the first time
|
|||
|
|
@cindex Importing modules
|
|||
|
|
|
|||
|
|
Use the @code{import} command to check in the sources
|
|||
|
|
for the first time. When you use the @code{import}
|
|||
|
|
command to track third-party sources, the @dfn{vendor
|
|||
|
|
tag} and @dfn{release tags} are useful. The
|
|||
|
|
@dfn{vendor tag} is a symbolic name for the branch
|
|||
|
|
(which is always 1.1.1, unless you use the @samp{-b
|
|||
|
|
@var{branch}} flag---@xref{import options}). The
|
|||
|
|
@dfn{release tags} are symbolic names for a particular
|
|||
|
|
release, such as @samp{FSF_0_04}.
|
|||
|
|
|
|||
|
|
@cindex Wdiff (import example)
|
|||
|
|
Suppose you use @code{wdiff} (a variant of @code{diff}
|
|||
|
|
that ignores changes that only involve whitespace), and
|
|||
|
|
are going to make private modifications that you want
|
|||
|
|
to be able to use even when new releases are made in
|
|||
|
|
the future. You start by importing the source to your
|
|||
|
|
repository:
|
|||
|
|
|
|||
|
|
@example
|
|||
|
|
$ tar xfz wdiff-0.04.tar.gz
|
|||
|
|
$ cd wdiff-0.04
|
|||
|
|
$ cvs import -m "Import of FSF v. 0.04" fsf/wdiff FSF_DIST WDIFF_0_04
|
|||
|
|
@end example
|
|||
|
|
|
|||
|
|
The vendor tag is named @samp{FSF_DIST} in the above
|
|||
|
|
example, and the only release tag assigned is
|
|||
|
|
@samp{WDIFF_0_04}.
|
|||
|
|
|
|||
|
|
@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
|
|||
|
|
@node Update imports
|
|||
|
|
@section Updating a module with the import command
|
|||
|
|
|
|||
|
|
When a new release of the source arrives, you import it into the
|
|||
|
|
repository with the same @code{import} command that you used to set up
|
|||
|
|
the repository in the first place. The only difference is that you
|
|||
|
|
specify a different release tag this time.
|
|||
|
|
|
|||
|
|
@example
|
|||
|
|
$ tar xfz wdiff-0.05.tar.gz
|
|||
|
|
$ cd wdiff-0.05
|
|||
|
|
$ cvs import -m "Import of FSF v. 0.05" fsf/wdiff FSF_DIST WDIFF_0_05
|
|||
|
|
@end example
|
|||
|
|
|
|||
|
|
For files that have not been modified locally, the newly created
|
|||
|
|
revision becomes the head revision. If you have made local
|
|||
|
|
changes, @code{import} will warn you that you must merge the changes
|
|||
|
|
into the main trunk, and tell you to use @samp{checkout -j} to do so.
|
|||
|
|
|
|||
|
|
@example
|
|||
|
|
$ cvs checkout -jFSF_DIST:yesterday -jFSF_DIST wdiff
|
|||
|
|
@end example
|
|||
|
|
|
|||
|
|
@noindent
|
|||
|
|
The above command will check out the latest revision of
|
|||
|
|
@samp{wdiff}, merging the changes made on the vendor branch @samp{FSF_DIST}
|
|||
|
|
since yesterday into the working copy. If any conflicts arise during
|
|||
|
|
the merge they should be resolved in the normal way (@pxref{Conflicts
|
|||
|
|
example}). Then, the modified files may be committed.
|
|||
|
|
|
|||
|
|
Using a date, as suggested above, assumes that you do
|
|||
|
|
not import more than one release of a product per
|
|||
|
|
day. If you do, you can always use something like this
|
|||
|
|
instead:
|
|||
|
|
|
|||
|
|
@example
|
|||
|
|
$ cvs checkout -jWDIFF_0_04 -jWDIFF_0_05 wdiff
|
|||
|
|
@end example
|
|||
|
|
|
|||
|
|
@noindent
|
|||
|
|
In this case, the two above commands are equivalent.
|
|||
|
|
|
|||
|
|
@c ---------------------------------------------------------------------
|
|||
|
|
@node Moving files
|
|||
|
|
@chapter Moving and renaming files
|
|||
|
|
@cindex Moving files
|
|||
|
|
@cindex Renaming files
|
|||
|
|
@cindex Files, moving
|
|||
|
|
|
|||
|
|
Moving files to a different directory or renaming them
|
|||
|
|
is not difficult, but some of the ways in which this
|
|||
|
|
works may be non-obvious. (Moving or renaming a
|
|||
|
|
directory is even harder. @xref{Moving directories}).
|
|||
|
|
|
|||
|
|
The examples below assume that the file @var{old} is renamed to
|
|||
|
|
@var{new}.
|
|||
|
|
|
|||
|
|
@menu
|
|||
|
|
* Outside:: The normal way to Rename
|
|||
|
|
* Inside:: A tricky, alternative way
|
|||
|
|
* Rename by copying:: Another tricky, alternative way
|
|||
|
|
@end menu
|
|||
|
|
|
|||
|
|
@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
|
|||
|
|
@node Outside
|
|||
|
|
@section The Normal way to Rename
|
|||
|
|
|
|||
|
|
The normal way to move a file is to copy @var{old} to
|
|||
|
|
@var{new}, and then issue the normal @sc{cvs} commands
|
|||
|
|
to remove @var{old} from the repository, and add
|
|||
|
|
@var{new} to it. (Both @var{old} and @var{new} could
|
|||
|
|
contain relative paths, for example @file{foo/bar.c}).
|
|||
|
|
|
|||
|
|
@example
|
|||
|
|
$ mv @var{old} @var{new}
|
|||
|
|
$ cvs remove @var{old}
|
|||
|
|
$ cvs add @var{new}
|
|||
|
|
$ cvs commit -m "Renamed @var{old} to @var{new}" @var{old} @var{new}
|
|||
|
|
@end example
|
|||
|
|
|
|||
|
|
This is the simplest way to move a file, it is not
|
|||
|
|
error-prone, and it preserves the history of what was
|
|||
|
|
done. Note that to access the history of the file you
|
|||
|
|
must specify the old or the new name, depending on what
|
|||
|
|
portion of the history you are accessing. For example,
|
|||
|
|
@code{cvs log @var{old}} will give the log up until the
|
|||
|
|
time of the rename.
|
|||
|
|
|
|||
|
|
When @var{new} is committed its revision numbers will
|
|||
|
|
start at 1.0 again, so if that bothers you, use the
|
|||
|
|
@samp{-r rev} option to commit (@pxref{commit options})
|
|||
|
|
|
|||
|
|
@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
|
|||
|
|
@node Inside
|
|||
|
|
@section Moving the history file
|
|||
|
|
|
|||
|
|
This method is more dangerous, since it involves moving
|
|||
|
|
files inside the repository. Read this entire section
|
|||
|
|
before trying it out!
|
|||
|
|
|
|||
|
|
@example
|
|||
|
|
$ cd $CVSROOT/@var{module}
|
|||
|
|
$ mv @var{old},v @var{new},v
|
|||
|
|
@end example
|
|||
|
|
|
|||
|
|
@noindent
|
|||
|
|
Advantages:
|
|||
|
|
|
|||
|
|
@itemize @bullet
|
|||
|
|
@item
|
|||
|
|
The log of changes is maintained intact.
|
|||
|
|
|
|||
|
|
@item
|
|||
|
|
The revision numbers are not affected.
|
|||
|
|
@end itemize
|
|||
|
|
|
|||
|
|
@noindent
|
|||
|
|
Disadvantages:
|
|||
|
|
|
|||
|
|
@itemize @bullet
|
|||
|
|
@item
|
|||
|
|
Old releases of the module cannot easily be fetched from the
|
|||
|
|
repository. (The file will show up as @var{new} even
|
|||
|
|
in revisions from the time before it was renamed).
|
|||
|
|
|
|||
|
|
@item
|
|||
|
|
There is no log information of when the file was renamed.
|
|||
|
|
|
|||
|
|
@item
|
|||
|
|
Nasty things might happen if someone accesses the history file
|
|||
|
|
while you are moving it. Make sure no one else runs any of the @sc{cvs}
|
|||
|
|
commands while you move it.
|
|||
|
|
@end itemize
|
|||
|
|
|
|||
|
|
@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
|
|||
|
|
@node Rename by copying
|
|||
|
|
@section Copying the history file
|
|||
|
|
|
|||
|
|
This way also involves direct modifications to the
|
|||
|
|
repository. It is safe, but not without drawbacks.
|
|||
|
|
|
|||
|
|
@example
|
|||
|
|
# @r{Copy the @sc{rcs} file inside the repository}
|
|||
|
|
$ cd $CVSROOT/@var{module}
|
|||
|
|
$ cp @var{old},v @var{new},v
|
|||
|
|
# @r{Remove the old file}
|
|||
|
|
$ cd ~/@var{module}
|
|||
|
|
$ rm @var{old}
|
|||
|
|
$ cvs remove @var{old}
|
|||
|
|
$ cvs commit @var{old}
|
|||
|
|
# @r{Remove all tags from @var{new}}
|
|||
|
|
$ cvs update @var{new}
|
|||
|
|
$ cvs log @var{new} # @r{Remember the tag names}
|
|||
|
|
$ cvs tag -d @var{tag1}
|
|||
|
|
$ cvs tag -d @var{tag2}
|
|||
|
|
@dots{}
|
|||
|
|
@end example
|
|||
|
|
|
|||
|
|
By removing the tags you will be able to check out old
|
|||
|
|
revisions of the module.
|
|||
|
|
|
|||
|
|
@noindent
|
|||
|
|
Advantages:
|
|||
|
|
|
|||
|
|
@itemize @bullet
|
|||
|
|
@item
|
|||
|
|
@c FIXME: Is this true about -D now that we have death
|
|||
|
|
@c support? See 5B.3 in the FAQ.
|
|||
|
|
Checking out old revisions works correctly, as long as
|
|||
|
|
you use @samp{-r@var{tag}} and not @samp{-D@var{date}}
|
|||
|
|
to retrieve the revisions.
|
|||
|
|
|
|||
|
|
@item
|
|||
|
|
The log of changes is maintained intact.
|
|||
|
|
|
|||
|
|
@item
|
|||
|
|
The revision numbers are not affected.
|
|||
|
|
@end itemize
|
|||
|
|
|
|||
|
|
@noindent
|
|||
|
|
Disadvantages:
|
|||
|
|
|
|||
|
|
@itemize @bullet
|
|||
|
|
@item
|
|||
|
|
You cannot easily see the history of the file across the rename.
|
|||
|
|
|
|||
|
|
@item
|
|||
|
|
Unless you use the @samp{-r rev} (@pxref{commit
|
|||
|
|
options}) flag when @var{new} is committed its revision
|
|||
|
|
numbers will start at 1.0 again.
|
|||
|
|
@end itemize
|
|||
|
|
|
|||
|
|
@c ---------------------------------------------------------------------
|
|||
|
|
@node Moving directories
|
|||
|
|
@chapter Moving and renaming directories
|
|||
|
|
@cindex Moving directories
|
|||
|
|
@cindex Renaming directories
|
|||
|
|
@cindex Directories, moving
|
|||
|
|
|
|||
|
|
If you want to be able to retrieve old versions of the
|
|||
|
|
module, you must move each file in the directory
|
|||
|
|
with the @sc{cvs} commands. @xref{Outside}. The old, empty
|
|||
|
|
directory will remain inside the repository, but it
|
|||
|
|
will not appear in your workspace when you check out
|
|||
|
|
the module in the future.
|
|||
|
|
@c -- rephrase
|
|||
|
|
|
|||
|
|
If you really want to rename or delete a directory, you
|
|||
|
|
can do it like this:
|
|||
|
|
|
|||
|
|
@enumerate
|
|||
|
|
@item
|
|||
|
|
Inform everyone who has a copy of the module that the
|
|||
|
|
directory will be renamed. They should commit all
|
|||
|
|
their changes, and remove their working copies of the
|
|||
|
|
module, before you take the steps below.
|
|||
|
|
|
|||
|
|
@item
|
|||
|
|
Rename the directory inside the repository.
|
|||
|
|
|
|||
|
|
@example
|
|||
|
|
$ cd $CVSROOT/@var{module}
|
|||
|
|
$ mv @var{old-dir} @var{new-dir}
|
|||
|
|
@end example
|
|||
|
|
|
|||
|
|
@item
|
|||
|
|
Fix the @sc{cvs} administrative files, if necessary (for
|
|||
|
|
instance if you renamed an entire module).
|
|||
|
|
|
|||
|
|
@item
|
|||
|
|
Tell everyone that they can check out the module and continue
|
|||
|
|
working.
|
|||
|
|
|
|||
|
|
@end enumerate
|
|||
|
|
|
|||
|
|
If someone had a working copy of the module the @sc{cvs} commands will
|
|||
|
|
cease to work for him, until he removes the directory
|
|||
|
|
that disappeared inside the repository.
|
|||
|
|
|
|||
|
|
It is almost always better to move the files in the
|
|||
|
|
directory instead of moving the directory. If you move the
|
|||
|
|
directory you are unlikely to be able to retrieve old
|
|||
|
|
releases correctly, since they probably depend on the
|
|||
|
|
name of the directories.
|
|||
|
|
|
|||
|
|
@c ---------------------------------------------------------------------
|
|||
|
|
@node History browsing
|
|||
|
|
@chapter History browsing
|
|||
|
|
@cindex History browsing
|
|||
|
|
@cindex Traceability
|
|||
|
|
@cindex Isolation
|
|||
|
|
|
|||
|
|
@ignore
|
|||
|
|
@c This is too long for an introduction (goal is
|
|||
|
|
@c one 20x80 character screen), and also mixes up a
|
|||
|
|
@c variety of issues (parallel development, history,
|
|||
|
|
@c maybe even touches on process control).
|
|||
|
|
|
|||
|
|
@c -- @quote{To lose ones history is to lose ones soul.}
|
|||
|
|
@c -- ///
|
|||
|
|
@c -- ///Those who cannot remember the past are condemned to repeat it.
|
|||
|
|
@c -- /// -- George Santayana
|
|||
|
|
@c -- ///
|
|||
|
|
|
|||
|
|
@sc{cvs} tries to make it easy for a group of people to work
|
|||
|
|
together. This is done in two ways:
|
|||
|
|
|
|||
|
|
@itemize @bullet
|
|||
|
|
@item
|
|||
|
|
Isolation---You have your own working copy of the
|
|||
|
|
source. You are not affected by modifications made by
|
|||
|
|
others until you decide to incorporate those changes
|
|||
|
|
(via the @code{update} command---@pxref{update}).
|
|||
|
|
|
|||
|
|
@item
|
|||
|
|
Traceability---When something has changed, you can
|
|||
|
|
always see @emph{exactly} what changed.
|
|||
|
|
@end itemize
|
|||
|
|
|
|||
|
|
There are several features of @sc{cvs} that together lead
|
|||
|
|
to traceability:
|
|||
|
|
|
|||
|
|
@itemize @bullet
|
|||
|
|
@item
|
|||
|
|
Each revision of a file has an accompanying log
|
|||
|
|
message.
|
|||
|
|
|
|||
|
|
@item
|
|||
|
|
All commits are optionally logged to a central history
|
|||
|
|
database.
|
|||
|
|
|
|||
|
|
@item
|
|||
|
|
Logging information can be sent to a user-defined
|
|||
|
|
program (@pxref{loginfo}).
|
|||
|
|
@end itemize
|
|||
|
|
|
|||
|
|
@c -- More text here.
|
|||
|
|
|
|||
|
|
This chapter should talk about the history file, the
|
|||
|
|
@code{log} command, the usefulness of ChangeLogs
|
|||
|
|
even when you run @sc{cvs}, and things like that.
|
|||
|
|
|
|||
|
|
@end ignore
|
|||
|
|
|
|||
|
|
@c kind of lame, in a lot of ways the above text inside
|
|||
|
|
@c the @ignore motivates this chapter better
|
|||
|
|
Once you have used @sc{cvs} to store a version control
|
|||
|
|
history---what files have changed when, how, and by
|
|||
|
|
whom, there are a variety of mechanisms for looking
|
|||
|
|
through the history.
|
|||
|
|
|
|||
|
|
@menu
|
|||
|
|
* log messages:: Log messages
|
|||
|
|
* history database:: The history database
|
|||
|
|
* user-defined logging:: User-defined logging
|
|||
|
|
* annotate:: What revision modified each line of a file?
|
|||
|
|
@end menu
|
|||
|
|
|
|||
|
|
@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
|
|||
|
|
@node log messages
|
|||
|
|
@section Log messages
|
|||
|
|
|
|||
|
|
@c FIXME: @xref to place where we talk about how to
|
|||
|
|
@c specify message to commit.
|
|||
|
|
Whenever you commit a file you specify a log message.
|
|||
|
|
|
|||
|
|
@c FIXME: bring the information here, and get rid of or
|
|||
|
|
@c greatly shrink the "log" node.
|
|||
|
|
To look through the log messages which have been
|
|||
|
|
specified for every revision which has been committed,
|
|||
|
|
use the @code{cvs log} command (@pxref{log}).
|
|||
|
|
|
|||
|
|
@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
|
|||
|
|
@node history database
|
|||
|
|
@section The history database
|
|||
|
|
|
|||
|
|
@c FIXME: bring the information from the history file
|
|||
|
|
@c and history nodes here. Rewrite it to be motivated
|
|||
|
|
@c better (start out by clearly explaining what gets
|
|||
|
|
@c logged in history, for example).
|
|||
|
|
You can use the history file (@pxref{history file}) to
|
|||
|
|
log various @sc{cvs} actions. To retrieve the
|
|||
|
|
information from the history file, use the @code{cvs
|
|||
|
|
history} command (@pxref{history}).
|
|||
|
|
|
|||
|
|
@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
|
|||
|
|
@node user-defined logging
|
|||
|
|
@section User-defined logging
|
|||
|
|
|
|||
|
|
@c FIXME: should probably also mention the fact the -l
|
|||
|
|
@c global option can disable most of the mechanisms
|
|||
|
|
@c discussed here (why? What is the -l global option for?).
|
|||
|
|
@c
|
|||
|
|
@c FIXME: probably should centralize this information
|
|||
|
|
@c here, at least to some extent. Maybe by moving the
|
|||
|
|
@c loginfo, etc., nodes here and replacing
|
|||
|
|
@c the "user-defined logging" node with one node for
|
|||
|
|
@c each method.
|
|||
|
|
You can customize @sc{cvs} to log various kinds of
|
|||
|
|
actions, in whatever manner you choose. These
|
|||
|
|
mechanisms operate by executing a script at various
|
|||
|
|
times. The script might append a message to a file
|
|||
|
|
listing the information and the programmer who created
|
|||
|
|
it, or send mail to a group of developers, or, perhaps,
|
|||
|
|
post a message to a particular newsgroup. To log
|
|||
|
|
commits, use the @file{loginfo} file (@pxref{loginfo}).
|
|||
|
|
@c FIXME: What is difference between doing it in the
|
|||
|
|
@c modules file and using loginfo/taginfo? Why should
|
|||
|
|
@c user use one or the other?
|
|||
|
|
To log commits, checkouts, exports, and tags,
|
|||
|
|
respectively, you can also use the @samp{-i},
|
|||
|
|
@samp{-o}, @samp{-e}, and @samp{-t} options in the
|
|||
|
|
modules file. For a more flexible way of giving
|
|||
|
|
notifications to various users, which requires less in
|
|||
|
|
the way of keeping centralized scripts up to date, use
|
|||
|
|
the @code{cvs watch add} command (@pxref{Getting
|
|||
|
|
Notified}); this command is useful even if you are not
|
|||
|
|
using @code{cvs watch on}.
|
|||
|
|
|
|||
|
|
@cindex taginfo
|
|||
|
|
The @file{taginfo} file defines programs to execute
|
|||
|
|
when someone executes a @code{tag} or @code{rtag}
|
|||
|
|
command. The @file{taginfo} file has the standard form
|
|||
|
|
for administrative files (@pxref{Administrative
|
|||
|
|
files}), where each line is a regular expression
|
|||
|
|
followed by a command to execute. The arguments passed
|
|||
|
|
to the command are, in order, the @var{tagname},
|
|||
|
|
@var{operation} (@code{add} for @code{tag},
|
|||
|
|
@code{mov} for @code{tag -F}, and @code{del} for
|
|||
|
|
@code{tag -d}), @var{repository}, and any remaining are
|
|||
|
|
pairs of @var{filename} @var{revision}. A non-zero
|
|||
|
|
exit of the filter program will cause the tag to be
|
|||
|
|
aborted.
|
|||
|
|
|
|||
|
|
@node annotate
|
|||
|
|
@section Annotate command
|
|||
|
|
@cindex annotate (subcommand)
|
|||
|
|
|
|||
|
|
@deffn Command {cvs annotate} [@code{-l}] files @dots{}
|
|||
|
|
|
|||
|
|
For each file in @var{files}, print the head revision
|
|||
|
|
of the trunk, together with information on the last
|
|||
|
|
modification for each line. The @code{-l} option means
|
|||
|
|
to process the local directory only, not to recurse
|
|||
|
|
(@pxref{Common options}). For example:
|
|||
|
|
|
|||
|
|
@example
|
|||
|
|
$ cvs annotate ssfile
|
|||
|
|
Annotations for ssfile
|
|||
|
|
***************
|
|||
|
|
1.1 (mary 27-Mar-96): ssfile line 1
|
|||
|
|
1.2 (joe 28-Mar-96): ssfile line 2
|
|||
|
|
@end example
|
|||
|
|
|
|||
|
|
The file @file{ssfile} currently contains two lines.
|
|||
|
|
The @code{ssfile line 1} line was checked in by
|
|||
|
|
@code{mary} on March 27. Then, on March 28, @code{joe}
|
|||
|
|
added a line @code{ssfile line 2}, without modifying
|
|||
|
|
the @code{ssfile line 1} line. This report doesn't
|
|||
|
|
tell you anything about lines which have been deleted
|
|||
|
|
or replaced; you need to use @code{cvs diff} for that
|
|||
|
|
(@pxref{diff}).
|
|||
|
|
|
|||
|
|
@end deffn
|
|||
|
|
|
|||
|
|
@c ---------------------------------------------------------------------
|
|||
|
|
@node Keyword substitution
|
|||
|
|
@chapter Keyword substitution
|
|||
|
|
@cindex Keyword substitution
|
|||
|
|
@cindex Keyword expansion
|
|||
|
|
@cindex Identifying files
|
|||
|
|
|
|||
|
|
@comment Be careful when editing this chapter.
|
|||
|
|
@comment Remember that this file is kept under
|
|||
|
|
@comment version control, so we must not accidentally
|
|||
|
|
@comment include a valid keyword in the running text.
|
|||
|
|
|
|||
|
|
As long as you edit source files inside your working
|
|||
|
|
copy of a module you can always find out the state of
|
|||
|
|
your files via @samp{cvs status} and @samp{cvs log}.
|
|||
|
|
But as soon as you export the files from your
|
|||
|
|
development environment it becomes harder to identify
|
|||
|
|
which revisions they are.
|
|||
|
|
|
|||
|
|
@sc{Rcs} uses a mechanism known as @dfn{keyword
|
|||
|
|
substitution} (or @dfn{keyword expansion}) to help
|
|||
|
|
identifying the files. Embedded strings of the form
|
|||
|
|
@code{$@var{keyword}$} and
|
|||
|
|
@code{$@var{keyword}:@dots{}$} in a file are replaced
|
|||
|
|
with strings of the form
|
|||
|
|
@code{$@var{keyword}:@var{value}$} whenever you obtain
|
|||
|
|
a new revision of the file.
|
|||
|
|
|
|||
|
|
@menu
|
|||
|
|
* Keyword list:: RCS Keywords
|
|||
|
|
* Using keywords:: Using keywords
|
|||
|
|
* Avoiding substitution:: Avoiding substitution
|
|||
|
|
* Substitution modes:: Substitution modes
|
|||
|
|
* Log keyword:: Problems with the $@asis{}Log$ keyword.
|
|||
|
|
@end menu
|
|||
|
|
|
|||
|
|
@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
|
|||
|
|
@node Keyword list
|
|||
|
|
@section RCS Keywords
|
|||
|
|
@cindex RCS keywords
|
|||
|
|
|
|||
|
|
This is a list of the keywords that @sc{rcs} currently
|
|||
|
|
(in release 5.6.0.1) supports:
|
|||
|
|
|
|||
|
|
@table @code
|
|||
|
|
@cindex Author keyword
|
|||
|
|
@item $@asis{Author}$
|
|||
|
|
The login name of the user who checked in the revision.
|
|||
|
|
|
|||
|
|
@cindex Date keyword
|
|||
|
|
@item $@asis{Date}$
|
|||
|
|
The date and time (UTC) the revision was checked in.
|
|||
|
|
|
|||
|
|
@cindex Header keyword
|
|||
|
|
@item $@asis{Header}$
|
|||
|
|
A standard header containing the full pathname of the
|
|||
|
|
@sc{rcs} file, the revision number, the date (UTC), the
|
|||
|
|
author, the state, and the locker (if locked). Files
|
|||
|
|
will normally never be locked when you use @sc{cvs}.
|
|||
|
|
|
|||
|
|
@cindex Id keyword
|
|||
|
|
@item $@asis{Id}$
|
|||
|
|
Same as @code{$@asis{Header}$}, except that the @sc{rcs}
|
|||
|
|
filename is without a path.
|
|||
|
|
|
|||
|
|
@cindex Locker keyword
|
|||
|
|
@item $@asis{Locker}$
|
|||
|
|
The login name of the user who locked the revision
|
|||
|
|
(empty if not locked, and thus almost always useless
|
|||
|
|
when you are using @sc{cvs}).
|
|||
|
|
|
|||
|
|
@cindex Log keyword
|
|||
|
|
@item $@asis{Log}$
|
|||
|
|
The log message supplied during commit, preceded by a
|
|||
|
|
header containing the @sc{rcs} filename, the revision
|
|||
|
|
number, the author, and the date (UTC). Existing log
|
|||
|
|
messages are @emph{not} replaced. Instead, the new log
|
|||
|
|
message is inserted after @code{$@asis{Log:@dots{}}$}.
|
|||
|
|
Each new line is prefixed with a @dfn{comment leader}
|
|||
|
|
which @sc{rcs} guesses from the file name extension.
|
|||
|
|
It can be changed with @code{cvs admin -c}.
|
|||
|
|
@xref{admin options}. This keyword is useful for
|
|||
|
|
accumulating a complete change log in a source file,
|
|||
|
|
but for several reasons it can be problematic.
|
|||
|
|
@xref{Log keyword}.
|
|||
|
|
|
|||
|
|
@cindex RCSfile keyword
|
|||
|
|
@item $@asis{RCSfile}$
|
|||
|
|
The name of the RCS file without a path.
|
|||
|
|
|
|||
|
|
@cindex Revision keyword
|
|||
|
|
@item $@asis{Revision}$
|
|||
|
|
The revision number assigned to the revision.
|
|||
|
|
|
|||
|
|
@cindex Source keyword
|
|||
|
|
@item $@asis{Source}$
|
|||
|
|
The full pathname of the RCS file.
|
|||
|
|
|
|||
|
|
@cindex State keyword
|
|||
|
|
@item $@asis{State}$
|
|||
|
|
The state assigned to the revision. States can be
|
|||
|
|
assigned with @code{cvs admin -s}---@xref{admin options}.
|
|||
|
|
|
|||
|
|
@end table
|
|||
|
|
|
|||
|
|
@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
|
|||
|
|
@node Using keywords
|
|||
|
|
@section Using keywords
|
|||
|
|
|
|||
|
|
To include a keyword string you simply include the
|
|||
|
|
relevant text string, such as @code{$@asis{Id}$}, inside the
|
|||
|
|
file, and commit the file. @sc{cvs} will automatically
|
|||
|
|
expand the string as part of the commit operation.
|
|||
|
|
|
|||
|
|
@need 800
|
|||
|
|
It is common to embed @code{$@asis{}Id$} string in the
|
|||
|
|
C source code. This example shows the first few lines
|
|||
|
|
of a typical file, after keyword substitution has been
|
|||
|
|
performed:
|
|||
|
|
|
|||
|
|
@example
|
|||
|
|
static char *rcsid="$@asis{}Id: samp.c,v 1.5 1993/10/19 14:57:32 ceder Exp $";
|
|||
|
|
/* @r{The following lines will prevent @code{gcc} version 2.@var{x}}
|
|||
|
|
@r{from issuing an "unused variable" warning}. */
|
|||
|
|
#if __GNUC__ == 2
|
|||
|
|
#define USE(var) static void * use_##var = (&use_##var, (void *) &var)
|
|||
|
|
USE (rcsid);
|
|||
|
|
#endif
|
|||
|
|
@end example
|
|||
|
|
|
|||
|
|
Even though a clever optimizing compiler could remove
|
|||
|
|
the unused variable @code{rcsid}, most compilers tend
|
|||
|
|
to include the string in the binary. Some compilers
|
|||
|
|
have a @code{#pragma} directive to include literal text
|
|||
|
|
in the binary.
|
|||
|
|
|
|||
|
|
@cindex Ident (shell command)
|
|||
|
|
The @code{ident} command (which is part of the @sc{rcs}
|
|||
|
|
package) can be used to extract keywords and their
|
|||
|
|
values from a file. This can be handy for text files,
|
|||
|
|
but it is even more useful for extracting keywords from
|
|||
|
|
binary files.
|
|||
|
|
|
|||
|
|
@example
|
|||
|
|
$ ident samp.c
|
|||
|
|
samp.c:
|
|||
|
|
$@asis{}Id: samp.c,v 1.5 1993/10/19 14:57:32 ceder Exp $
|
|||
|
|
$ gcc samp.c
|
|||
|
|
$ ident a.out
|
|||
|
|
a.out:
|
|||
|
|
$@asis{}Id: samp.c,v 1.5 1993/10/19 14:57:32 ceder Exp $
|
|||
|
|
@end example
|
|||
|
|
|
|||
|
|
@cindex What (shell command)
|
|||
|
|
S@sc{ccs} is another popular revision control system.
|
|||
|
|
It has a command, @code{what}, which is very similar to
|
|||
|
|
@code{ident} and used for the same purpose. Many sites
|
|||
|
|
without @sc{rcs} have @sc{sccs}. Since @code{what}
|
|||
|
|
looks for the character sequence @code{@@(#)} it is
|
|||
|
|
easy to include keywords that are detected by either
|
|||
|
|
command. Simply prefix the @sc{rcs} keyword with the
|
|||
|
|
magic @sc{sccs} phrase, like this:
|
|||
|
|
|
|||
|
|
@example
|
|||
|
|
static char *id="@@(#) $@asis{}Id: ab.c,v 1.5 1993/10/19 14:57:32 ceder Exp $";
|
|||
|
|
@end example
|
|||
|
|
|
|||
|
|
@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
|
|||
|
|
@node Avoiding substitution
|
|||
|
|
@section Avoiding substitution
|
|||
|
|
|
|||
|
|
Keyword substitution has its disadvantages. Sometimes
|
|||
|
|
you might want the literal text string
|
|||
|
|
@samp{$@asis{}Author$} to appear inside a file without
|
|||
|
|
@sc{rcs} interpreting it as a keyword and expanding it
|
|||
|
|
into something like @samp{$@asis{}Author: ceder $}.
|
|||
|
|
|
|||
|
|
There is unfortunately no way to selectively turn off
|
|||
|
|
keyword substitution. You can use @samp{-ko}
|
|||
|
|
(@pxref{Substitution modes}) to turn off keyword
|
|||
|
|
substitution entirely.
|
|||
|
|
|
|||
|
|
In many cases you can avoid using @sc{rcs} keywords in
|
|||
|
|
the source, even though they appear in the final
|
|||
|
|
product. For example, the source for this manual
|
|||
|
|
contains @samp{$@@asis@{@}Author$} whenever the text
|
|||
|
|
@samp{$@asis{}Author$} should appear. In @code{nroff}
|
|||
|
|
and @code{troff} you can embed the null-character
|
|||
|
|
@code{\&} inside the keyword for a similar effect.
|
|||
|
|
|
|||
|
|
@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
|
|||
|
|
@node Substitution modes
|
|||
|
|
@section Substitution modes
|
|||
|
|
@cindex -k (RCS kflags)
|
|||
|
|
@cindex Kflag
|
|||
|
|
|
|||
|
|
@c FIXME: This could be made more coherent, by expanding it
|
|||
|
|
@c with more examples or something.
|
|||
|
|
Each file has a stored default substitution mode, and
|
|||
|
|
each working directory copy of a file also has a
|
|||
|
|
substitution mode. The former is set by the @samp{-k}
|
|||
|
|
option to @code{cvs add} and @code{cvs admin}; the
|
|||
|
|
latter is set by the -k or -A options to @code{cvs
|
|||
|
|
checkout} or @code{cvs update}. @code{cvs diff} also
|
|||
|
|
has a @samp{-k} option. For some examples,
|
|||
|
|
@xref{Binary files}.
|
|||
|
|
|
|||
|
|
The modes available are:
|
|||
|
|
|
|||
|
|
@table @samp
|
|||
|
|
@item -kkv
|
|||
|
|
Generate keyword strings using the default form, e.g.
|
|||
|
|
@code{$@asis{}Revision: 5.7 $} for the @code{Revision}
|
|||
|
|
keyword.
|
|||
|
|
|
|||
|
|
@item -kkvl
|
|||
|
|
Like @samp{-kkv}, except that a locker's name is always
|
|||
|
|
inserted if the given revision is currently locked.
|
|||
|
|
This option is normally not useful when @sc{cvs} is used.
|
|||
|
|
|
|||
|
|
@item -kk
|
|||
|
|
Generate only keyword names in keyword strings; omit
|
|||
|
|
their values. For example, for the @code{Revision}
|
|||
|
|
keyword, generate the string @code{$@asis{}Revision$}
|
|||
|
|
instead of @code{$@asis{}Revision: 5.7 $}. This option
|
|||
|
|
is useful to ignore differences due to keyword
|
|||
|
|
substitution when comparing different revisions of a
|
|||
|
|
file.
|
|||
|
|
|
|||
|
|
@item -ko
|
|||
|
|
Generate the old keyword string, present in the working
|
|||
|
|
file just before it was checked in. For example, for
|
|||
|
|
the @code{Revision} keyword, generate the string
|
|||
|
|
@code{$@asis{}Revision: 1.1 $} instead of
|
|||
|
|
@code{$@asis{}Revision: 5.7 $} if that is how the
|
|||
|
|
string appeared when the file was checked in.
|
|||
|
|
|
|||
|
|
@item -kb
|
|||
|
|
Like @samp{-ko}, but also inhibit conversion of line
|
|||
|
|
endings between the canonical form in which they are
|
|||
|
|
stored in the repository (linefeed only), and the form
|
|||
|
|
appropriate to the operating system in use on the
|
|||
|
|
client. For systems, like unix, which use linefeed
|
|||
|
|
only to terminate lines, this is the same as
|
|||
|
|
@samp{-ko}. For more information on binary files, see
|
|||
|
|
@ref{Binary files}.
|
|||
|
|
|
|||
|
|
@item -kv
|
|||
|
|
Generate only keyword values for keyword strings. For
|
|||
|
|
example, for the @code{Revision} keyword, generate the string
|
|||
|
|
@code{5.7} instead of @code{$@asis{}Revision: 5.7 $}.
|
|||
|
|
This can help generate files in programming languages
|
|||
|
|
where it is hard to strip keyword delimiters like
|
|||
|
|
@code{$@asis{}Revision: $} from a string. However,
|
|||
|
|
further keyword substitution cannot be performed once
|
|||
|
|
the keyword names are removed, so this option should be
|
|||
|
|
used with care.
|
|||
|
|
|
|||
|
|
One often would like to use @samp{-kv} with @code{cvs
|
|||
|
|
export}---@pxref{export}. But be aware that doesn't
|
|||
|
|
handle an export containing binary files correctly.
|
|||
|
|
|
|||
|
|
@end table
|
|||
|
|
|
|||
|
|
@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
|
|||
|
|
@node Log keyword
|
|||
|
|
@section Problems with the $@asis{}Log$ keyword.
|
|||
|
|
|
|||
|
|
The @code{$@asis{}Log$} keyword is somewhat
|
|||
|
|
controversial. As long as you are working on your
|
|||
|
|
development system the information is easily accessible
|
|||
|
|
even if you do not use the @code{$@asis{}Log$}
|
|||
|
|
keyword---just do a @code{cvs log}. Once you export
|
|||
|
|
the file the history information might be useless
|
|||
|
|
anyhow.
|
|||
|
|
|
|||
|
|
A more serious concern is that @sc{rcs} is not good at
|
|||
|
|
handling @code{$@asis{}Log$} entries when a branch is
|
|||
|
|
merged onto the main trunk. Conflicts often result
|
|||
|
|
from the merging operation.
|
|||
|
|
|
|||
|
|
People also tend to "fix" the log entries in the file
|
|||
|
|
(correcting spelling mistakes and maybe even factual
|
|||
|
|
errors). If that is done the information from
|
|||
|
|
@code{cvs log} will not be consistent with the
|
|||
|
|
information inside the file. This may or may not be a
|
|||
|
|
problem in real life.
|
|||
|
|
|
|||
|
|
It has been suggested that the @code{$@asis{}Log$}
|
|||
|
|
keyword should be inserted @emph{last} in the file, and
|
|||
|
|
not in the files header, if it is to be used at all.
|
|||
|
|
That way the long list of change messages will not
|
|||
|
|
interfere with everyday source file browsing.
|
|||
|
|
|
|||
|
|
@c ---------------------------------------------------------------------
|
|||
|
|
@node Binary files
|
|||
|
|
@chapter Handling binary files
|
|||
|
|
@cindex Binary files
|
|||
|
|
|
|||
|
|
There are two issues with using @sc{cvs} to store
|
|||
|
|
binary files. The first is that @sc{cvs} by default
|
|||
|
|
convert line endings between the canonical form in
|
|||
|
|
which they are stored in the repository (linefeed
|
|||
|
|
only), and the form appropriate to the operating system
|
|||
|
|
in use on the client (for example, carriage return
|
|||
|
|
followed by line feed for Windows NT).
|
|||
|
|
|
|||
|
|
The second is that a binary file might happen to
|
|||
|
|
contain data which looks like a keyword (@pxref{Keyword
|
|||
|
|
substitution}), so keyword expansion must be turned
|
|||
|
|
off.
|
|||
|
|
|
|||
|
|
The @samp{-kb} option available with some @sc{cvs}
|
|||
|
|
commands insures that neither line ending conversion
|
|||
|
|
nor keyword expansion will be done. If you are using
|
|||
|
|
an old version of @sc{rcs} without this option, and you
|
|||
|
|
are using an operating system, such as unix, which
|
|||
|
|
terminates lines with linefeeds only, you can use
|
|||
|
|
@samp{-ko} instead; if you are on another operating
|
|||
|
|
system, upgrade to a version of @sc{rcs}, such as 5.7
|
|||
|
|
or later, which supports @samp{-kb}.
|
|||
|
|
|
|||
|
|
Here is an example of how you can create a new file
|
|||
|
|
using the @samp{-kb} flag:
|
|||
|
|
|
|||
|
|
@example
|
|||
|
|
$ echo '$@asis{}Id$' > kotest
|
|||
|
|
$ cvs add -kb -m"A test file" kotest
|
|||
|
|
$ cvs ci -m"First checkin; contains a keyword" kotest
|
|||
|
|
@end example
|
|||
|
|
|
|||
|
|
If a file accidentally gets added without @samp{-kb},
|
|||
|
|
one can use the @code{cvs admin} command to recover.
|
|||
|
|
For example:
|
|||
|
|
|
|||
|
|
@example
|
|||
|
|
$ echo '$@asis{}Id$' > kotest
|
|||
|
|
$ cvs add -m"A test file" kotest
|
|||
|
|
$ cvs ci -m"First checkin; contains a keyword" kotest
|
|||
|
|
$ cvs admin -kb kotest
|
|||
|
|
$ cvs update -A kotest
|
|||
|
|
@end example
|
|||
|
|
|
|||
|
|
When you check in the file @file{kotest} the keywords
|
|||
|
|
are expanded. (Try the above example, and do a
|
|||
|
|
@code{cat kotest} after every command). The @code{cvs
|
|||
|
|
admin -kb} command sets the default keyword
|
|||
|
|
substitution method for this file, but it does not
|
|||
|
|
alter the working copy of the file that you have. The
|
|||
|
|
easiest way to get the unexpanded version of
|
|||
|
|
@file{kotest} is @code{cvs update -A}.
|
|||
|
|
|
|||
|
|
@c ---------------------------------------------------------------------
|
|||
|
|
@node Revision management
|
|||
|
|
@chapter Revision management
|
|||
|
|
@cindex Revision management
|
|||
|
|
|
|||
|
|
@c -- This chapter could be expanded a lot.
|
|||
|
|
@c -- Experiences are very welcome!
|
|||
|
|
|
|||
|
|
If you have read this far, you probably have a pretty
|
|||
|
|
good grasp on what @sc{cvs} can do for you. This
|
|||
|
|
chapter talks a little about things that you still have
|
|||
|
|
to decide.
|
|||
|
|
|
|||
|
|
If you are doing development on your own using @sc{cvs}
|
|||
|
|
you could probably skip this chapter. The questions
|
|||
|
|
this chapter takes up become more important when more
|
|||
|
|
than one person is working in a repository.
|
|||
|
|
|
|||
|
|
@menu
|
|||
|
|
* When to commit:: Some discussion on the subject
|
|||
|
|
@end menu
|
|||
|
|
|
|||
|
|
@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
|
|||
|
|
@node When to commit
|
|||
|
|
@section When to commit?
|
|||
|
|
@cindex When to commit
|
|||
|
|
@cindex Commit, when to
|
|||
|
|
@cindex Policy
|
|||
|
|
|
|||
|
|
Your group should decide which policy to use regarding
|
|||
|
|
commits. Several policies are possible, and as your
|
|||
|
|
experience with @sc{cvs} grows you will probably find
|
|||
|
|
out what works for you.
|
|||
|
|
|
|||
|
|
If you commit files too quickly you might commit files
|
|||
|
|
that do not even compile. If your partner updates his
|
|||
|
|
working sources to include your buggy file, he will be
|
|||
|
|
unable to compile the code. On the other hand, other
|
|||
|
|
persons will not be able to benefit from the
|
|||
|
|
improvements you make to the code if you commit very
|
|||
|
|
seldom, and conflicts will probably be more common.
|
|||
|
|
|
|||
|
|
It is common to only commit files after making sure
|
|||
|
|
that they can be compiled. Some sites require that the
|
|||
|
|
files pass a test suite. Policies like this can be
|
|||
|
|
enforced using the commitinfo file
|
|||
|
|
(@pxref{commitinfo}), but you should think twice before
|
|||
|
|
you enforce such a convention. By making the
|
|||
|
|
development environment too controlled it might become
|
|||
|
|
too regimented and thus counter-productive to the real
|
|||
|
|
goal, which is to get software written.
|
|||
|
|
|
|||
|
|
@c ---------------------------------------------------------------------
|
|||
|
|
@node Invoking CVS
|
|||
|
|
@appendix Reference manual for CVS commands
|
|||
|
|
@cindex Command reference
|
|||
|
|
@cindex Reference, commands
|
|||
|
|
@cindex Invoking CVS
|
|||
|
|
|
|||
|
|
This appendix describes how to invoke @sc{cvs}, and
|
|||
|
|
describes in detail those subcommands of @sc{cvs} which
|
|||
|
|
are not fully described elsewhere. To look up a
|
|||
|
|
particular subcommand, see @ref{Index}.
|
|||
|
|
|
|||
|
|
@menu
|
|||
|
|
* Structure:: Overall structure of CVS commands
|
|||
|
|
* ~/.cvsrc:: Default options with the ~/.csvrc file
|
|||
|
|
* Global options:: Options you give to the left of cvs_command
|
|||
|
|
* Common options:: Options you give to the right of cvs_command
|
|||
|
|
* add:: Add a new file/directory to the repository
|
|||
|
|
* admin:: Administration front end for rcs
|
|||
|
|
* checkout:: Checkout sources for editing
|
|||
|
|
* commit:: Check files into the repository
|
|||
|
|
* diff:: Run diffs between revisions
|
|||
|
|
* export:: Export sources from CVS, similar to checkout
|
|||
|
|
* history:: Show status of files and users
|
|||
|
|
* import:: Import sources into CVS, using vendor branches
|
|||
|
|
* log:: Print out 'rlog' information for files
|
|||
|
|
* rdiff:: 'patch' format diffs between releases
|
|||
|
|
* release:: Indicate that a Module is no longer in use
|
|||
|
|
* rtag:: Add a tag to a module
|
|||
|
|
* status:: Status info on the revisions
|
|||
|
|
* tag:: Add a tag to checked out version
|
|||
|
|
* update:: Bring work tree in sync with repository
|
|||
|
|
@end menu
|
|||
|
|
|
|||
|
|
@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
|
|||
|
|
@node Structure
|
|||
|
|
@appendixsec Overall structure of CVS commands
|
|||
|
|
@cindex Structure
|
|||
|
|
@cindex CVS command structure
|
|||
|
|
@cindex Command structure
|
|||
|
|
@cindex Format of CVS commands
|
|||
|
|
|
|||
|
|
The first release of @sc{cvs} consisted of a number of shell-scripts.
|
|||
|
|
Today @sc{cvs} is implemented as a single program that is a front-end
|
|||
|
|
to @sc{rcs} and @code{diff}. The overall format of all
|
|||
|
|
@sc{cvs} commands is:
|
|||
|
|
|
|||
|
|
@example
|
|||
|
|
cvs [ cvs_options ] cvs_command [ command_options ] [ command_args ]
|
|||
|
|
@end example
|
|||
|
|
|
|||
|
|
@table @code
|
|||
|
|
@item cvs
|
|||
|
|
The program that is a front-end to @sc{rcs}.
|
|||
|
|
|
|||
|
|
@item cvs_options
|
|||
|
|
Some options that affect all sub-commands of @sc{cvs}. These are
|
|||
|
|
described below.
|
|||
|
|
|
|||
|
|
@item cvs_command
|
|||
|
|
One of several different sub-commands. Some of the commands have
|
|||
|
|
aliases that can be used instead; those aliases are noted in the
|
|||
|
|
reference manual for that command. There are only two situations
|
|||
|
|
where you may omit @samp{cvs_command}: @samp{cvs -H} elicits a
|
|||
|
|
list of available commands, and @samp{cvs -v} displays version
|
|||
|
|
information on @sc{cvs} itself.
|
|||
|
|
|
|||
|
|
@item command_options
|
|||
|
|
Options that are specific for the command.
|
|||
|
|
|
|||
|
|
@item command_args
|
|||
|
|
Arguments to the commands.
|
|||
|
|
@end table
|
|||
|
|
|
|||
|
|
There is unfortunately some confusion between
|
|||
|
|
@code{cvs_options} and @code{command_options}.
|
|||
|
|
@samp{-l}, when given as a @code{cvs_option}, only
|
|||
|
|
affects some of the commands. When it is given as a
|
|||
|
|
@code{command_option} is has a different meaning, and
|
|||
|
|
is accepted by more commands. In other words, do not
|
|||
|
|
take the above categorization too seriously. Look at
|
|||
|
|
the documentation instead.
|
|||
|
|
|
|||
|
|
@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
|
|||
|
|
@node ~/.cvsrc
|
|||
|
|
@appendixsec Default options and the ~/.cvsrc file
|
|||
|
|
@cindex .cvsrc file
|
|||
|
|
@cindex option defaults
|
|||
|
|
|
|||
|
|
There are some @code{command_options} that are used so
|
|||
|
|
often that you might have set up an alias or some other
|
|||
|
|
means to make sure you always specify that option. One
|
|||
|
|
example (the one that drove the implementation of the
|
|||
|
|
.cvsrc support, actually) is that many people find the
|
|||
|
|
default output of the @samp{diff} command to be very
|
|||
|
|
hard to read, and that either context diffs or unidiffs
|
|||
|
|
are much easier to understand.
|
|||
|
|
|
|||
|
|
The @file{~/.cvsrc} file is a way that you can add
|
|||
|
|
default options to @code{cvs_commands} within cvs,
|
|||
|
|
instead of relying on aliases or other shell scripts.
|
|||
|
|
|
|||
|
|
The format of the @file{~/.cvsrc} file is simple. The
|
|||
|
|
file is searched for a line that begins with the same
|
|||
|
|
name as the @code{cvs_command} being executed. If a
|
|||
|
|
match is found, then the remainder of the line is split
|
|||
|
|
up (at whitespace characters) into separate options and
|
|||
|
|
added to the command arguments @emph{before} any
|
|||
|
|
options from the command line.
|
|||
|
|
|
|||
|
|
If a command has two names (e.g., @code{checkout} and
|
|||
|
|
@code{co}), the official name, not necessarily the one
|
|||
|
|
used on the command line, will be used to match against
|
|||
|
|
the file. So if this is the contents of the user's
|
|||
|
|
@file{~/.cvsrc} file:
|
|||
|
|
|
|||
|
|
@example
|
|||
|
|
log -N
|
|||
|
|
diff -u
|
|||
|
|
update -P
|
|||
|
|
co -P
|
|||
|
|
@end example
|
|||
|
|
|
|||
|
|
@noindent
|
|||
|
|
the command @samp{cvs checkout foo} would have the
|
|||
|
|
@samp{-P} option added to the arguments, as well as
|
|||
|
|
@samp{cvs co foo}.
|
|||
|
|
|
|||
|
|
With the example file above, the output from @samp{cvs
|
|||
|
|
diff foobar} will be in unidiff format. @samp{cvs diff
|
|||
|
|
-c foobar} will provide context diffs, as usual.
|
|||
|
|
Getting "old" format diffs would be slightly more
|
|||
|
|
complicated, because @code{diff} doesn't have an option
|
|||
|
|
to specify use of the "old" format, so you would need
|
|||
|
|
@samp{cvs -f diff foobar}.
|
|||
|
|
|
|||
|
|
In place of the command name you can use @code{cvs} to
|
|||
|
|
specify global options (@pxref{Global options}). For
|
|||
|
|
example the following line in @file{.cvsrc}
|
|||
|
|
|
|||
|
|
@example
|
|||
|
|
cvs -z6
|
|||
|
|
@end example
|
|||
|
|
|
|||
|
|
causes @sc{cvs} to use compression level 6
|
|||
|
|
|
|||
|
|
@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
|
|||
|
|
@node Global options
|
|||
|
|
@appendixsec Global options
|
|||
|
|
@cindex Options, global
|
|||
|
|
@cindex Global options
|
|||
|
|
@cindex Left-hand options
|
|||
|
|
|
|||
|
|
The available @samp{cvs_options} (that are given to the
|
|||
|
|
left of @samp{cvs_command}) are:
|
|||
|
|
|
|||
|
|
@table @code
|
|||
|
|
@cindex RCSBIN, overriding
|
|||
|
|
@cindex Overriding RCSBIN
|
|||
|
|
@item -b @var{bindir}
|
|||
|
|
Use @var{bindir} as the directory where @sc{rcs} programs are
|
|||
|
|
located. Overrides the setting of the @code{$RCSBIN} environment
|
|||
|
|
variable and any precompiled directory. This parameter should be
|
|||
|
|
specified as an absolute pathname.
|
|||
|
|
|
|||
|
|
@cindex CVSROOT, overriding
|
|||
|
|
@cindex Overriding CVSROOT
|
|||
|
|
@item -d @var{cvs_root_directory}
|
|||
|
|
Use @var{cvs_root_directory} as the root directory
|
|||
|
|
pathname of the repository. Overrides the setting of
|
|||
|
|
the @code{$CVSROOT} environment variable. @xref{Repository}.
|
|||
|
|
|
|||
|
|
@cindex EDITOR, overriding
|
|||
|
|
@cindex Overriding EDITOR
|
|||
|
|
@item -e @var{editor}
|
|||
|
|
Use @var{editor} to enter revision log information. Overrides the
|
|||
|
|
setting of the @code{$CVSEDITOR} and @code{$EDITOR} environment variables.
|
|||
|
|
|
|||
|
|
@item -f
|
|||
|
|
Do not read the @file{~/.cvsrc} file. This
|
|||
|
|
option is most often used because of the
|
|||
|
|
non-orthogonality of the @sc{cvs} option set. For
|
|||
|
|
example, the @samp{cvs log} option @samp{-N} (turn off
|
|||
|
|
display of tag names) does not have a corresponding
|
|||
|
|
option to turn the display on. So if you have
|
|||
|
|
@samp{-N} in the @file{~/.cvsrc} entry for @samp{diff},
|
|||
|
|
you may need to use @samp{-f} to show the tag names.
|
|||
|
|
@footnote{Yes, this really should be fixed, and it's
|
|||
|
|
being worked on}
|
|||
|
|
|
|||
|
|
@item -H
|
|||
|
|
Display usage information about the specified @samp{cvs_command}
|
|||
|
|
(but do not actually execute the command). If you don't specify
|
|||
|
|
a command name, @samp{cvs -H} displays a summary of all the
|
|||
|
|
commands available.
|
|||
|
|
|
|||
|
|
@item -l
|
|||
|
|
Do not log the cvs_command in the command history (but execute it
|
|||
|
|
anyway). @xref{history}, for information on command history.
|
|||
|
|
|
|||
|
|
@cindex Read-only mode
|
|||
|
|
@item -n
|
|||
|
|
Do not change any files. Attempt to execute the
|
|||
|
|
@samp{cvs_command}, but only to issue reports; do not remove,
|
|||
|
|
update, or merge any existing files, or create any new files.
|
|||
|
|
|
|||
|
|
@item -Q
|
|||
|
|
Cause the command to be really quiet; the command will only
|
|||
|
|
generate output for serious problems.
|
|||
|
|
|
|||
|
|
@item -q
|
|||
|
|
Cause the command to be somewhat quiet; informational messages,
|
|||
|
|
such as reports of recursion through subdirectories, are
|
|||
|
|
suppressed.
|
|||
|
|
|
|||
|
|
@cindex Read-only files
|
|||
|
|
@item -r
|
|||
|
|
Make new working files files read-only. Same effect
|
|||
|
|
as if the @code{$CVSREAD} environment variable is set
|
|||
|
|
(@pxref{Environment variables}). The default is to
|
|||
|
|
make working files writable, unless watches are on
|
|||
|
|
(@pxref{Watches}).
|
|||
|
|
|
|||
|
|
@item -s @var{variable}=@var{value}
|
|||
|
|
Set a user variable (@pxref{Variables}).
|
|||
|
|
|
|||
|
|
@cindex Trace
|
|||
|
|
@item -t
|
|||
|
|
Trace program execution; display messages showing the steps of
|
|||
|
|
@sc{cvs} activity. Particularly useful with @samp{-n} to explore the
|
|||
|
|
potential impact of an unfamiliar command.
|
|||
|
|
|
|||
|
|
@item -v
|
|||
|
|
Display version and copyright information for @sc{cvs}.
|
|||
|
|
|
|||
|
|
@cindex CVSREAD, overriding
|
|||
|
|
@cindex Overriding CVSREAD
|
|||
|
|
@item -w
|
|||
|
|
Make new working files read-write. Overrides the
|
|||
|
|
setting of the @code{$CVSREAD} environment variable.
|
|||
|
|
Files are created read-write by default, unless @code{$CVSREAD} is
|
|||
|
|
set or @samp{-r} is given.
|
|||
|
|
|
|||
|
|
@item -z @var{gzip-level}
|
|||
|
|
Set the compression level. Only has an effect on the
|
|||
|
|
@sc{cvs} client.
|
|||
|
|
|
|||
|
|
@end table
|
|||
|
|
|
|||
|
|
@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
|
|||
|
|
@node Common options
|
|||
|
|
@appendixsec Common command options
|
|||
|
|
@cindex Common options
|
|||
|
|
@cindex Right-hand options
|
|||
|
|
|
|||
|
|
This section describes the @samp{command_options} that
|
|||
|
|
are available across several @sc{cvs} commands. These
|
|||
|
|
options are always given to the right of
|
|||
|
|
@samp{cvs_command}. Not all
|
|||
|
|
commands support all of these options; each option is
|
|||
|
|
only supported for commands where it makes sense.
|
|||
|
|
However, when a command has one of these options you
|
|||
|
|
can almost always count on the same behavior of the
|
|||
|
|
option as in other commands. (Other command options,
|
|||
|
|
which are listed with the individual commands, may have
|
|||
|
|
different behavior from one @sc{cvs} command to the other).
|
|||
|
|
|
|||
|
|
@strong{Warning:} the @samp{history} command is an exception; it supports
|
|||
|
|
many options that conflict even with these standard options.
|
|||
|
|
|
|||
|
|
@table @code
|
|||
|
|
@cindex Dates
|
|||
|
|
@cindex Time
|
|||
|
|
@cindex Specifying dates
|
|||
|
|
@item -D @var{date_spec}
|
|||
|
|
Use the most recent revision no later than @var{date_spec}.
|
|||
|
|
@var{date_spec} is a single argument, a date description
|
|||
|
|
specifying a date in the past.
|
|||
|
|
|
|||
|
|
The specification is @dfn{sticky} when you use it to make a
|
|||
|
|
private copy of a source file; that is, when you get a working
|
|||
|
|
file using @samp{-D}, @sc{cvs} records the date you specified, so that
|
|||
|
|
further updates in the same directory will use the same date
|
|||
|
|
(for more information on sticky tags/dates, @pxref{Sticky tags}).
|
|||
|
|
|
|||
|
|
A wide variety of date formats are supported by the underlying
|
|||
|
|
@sc{rcs} facilities, similar to those described in co(1), but not
|
|||
|
|
exactly the same. The @var{date_spec} is interpreted as being
|
|||
|
|
in the local timezone, unless a specific timezone is specified.
|
|||
|
|
Examples of valid date specifications include:
|
|||
|
|
|
|||
|
|
@example
|
|||
|
|
1 month ago
|
|||
|
|
2 hours ago
|
|||
|
|
400000 seconds ago
|
|||
|
|
last year
|
|||
|
|
last Monday
|
|||
|
|
yesterday
|
|||
|
|
a fortnight ago
|
|||
|
|
3/31/92 10:00:07 PST
|
|||
|
|
January 23, 1987 10:05pm
|
|||
|
|
22:00 GMT
|
|||
|
|
@end example
|
|||
|
|
|
|||
|
|
@samp{-D} is available with the @code{checkout},
|
|||
|
|
@code{diff}, @code{export}, @code{history},
|
|||
|
|
@code{rdiff}, @code{rtag}, and @code{update} commands.
|
|||
|
|
(The @code{history} command uses this option in a
|
|||
|
|
slightly different way; @pxref{history options}).
|
|||
|
|
|
|||
|
|
Remember to quote the argument to the @samp{-D}
|
|||
|
|
flag so that your shell doesn't interpret spaces as
|
|||
|
|
argument separators. A command using the @samp{-D}
|
|||
|
|
flag can look like this:
|
|||
|
|
|
|||
|
|
@example
|
|||
|
|
$ cvs diff -D "1 hour ago" cvs.texinfo
|
|||
|
|
@end example
|
|||
|
|
|
|||
|
|
@cindex Forcing a tag match
|
|||
|
|
@item -f
|
|||
|
|
When you specify a particular date or tag to @sc{cvs} commands, they
|
|||
|
|
normally ignore files that do not contain the tag (or did not
|
|||
|
|
exist prior to the date) that you specified. Use the @samp{-f} option
|
|||
|
|
if you want files retrieved even when there is no match for the
|
|||
|
|
tag or date. (The most recent revision of the file
|
|||
|
|
will be used).
|
|||
|
|
|
|||
|
|
@need 800
|
|||
|
|
@samp{-f} is available with these commands: @code{checkout},
|
|||
|
|
@code{export}, @code{rdiff}, @code{rtag}, and @code{update}.
|
|||
|
|
|
|||
|
|
@strong{Warning:} The @code{commit} command also has a
|
|||
|
|
@samp{-f} option, but it has a different behavior for
|
|||
|
|
that command. @xref{commit options}.
|
|||
|
|
|
|||
|
|
@item -H
|
|||
|
|
Help; describe the options available for this command. This is
|
|||
|
|
the only option supported for all @sc{cvs} commands.
|
|||
|
|
|
|||
|
|
@item -k @var{kflag}
|
|||
|
|
Alter the default @sc{rcs} processing of keywords.
|
|||
|
|
@xref{Keyword substitution}, for the meaning of
|
|||
|
|
@var{kflag}. Your @var{kflag} specification is
|
|||
|
|
@dfn{sticky} when you use it to create a private copy
|
|||
|
|
of a source file; that is, when you use this option
|
|||
|
|
with the @code{checkout} or @code{update} commands,
|
|||
|
|
@sc{cvs} associates your selected @var{kflag} with the
|
|||
|
|
file, and continues to use it with future update
|
|||
|
|
commands on the same file until you specify otherwise.
|
|||
|
|
|
|||
|
|
The @samp{-k} option is available with the @code{add},
|
|||
|
|
@code{checkout}, @code{diff} and
|
|||
|
|
@code{update} commands.
|
|||
|
|
|
|||
|
|
@item -l
|
|||
|
|
Local; run only in current working directory, rather than
|
|||
|
|
recursing through subdirectories.
|
|||
|
|
|
|||
|
|
@strong{Warning:} this is not the same
|
|||
|
|
as the overall @samp{cvs -l} option, which you can specify to the
|
|||
|
|
left of a cvs command!
|
|||
|
|
|
|||
|
|
Available with the following commands: @code{checkout},
|
|||
|
|
@code{commit}, @code{diff}, @code{export}, @code{log},
|
|||
|
|
@code{remove}, @code{rdiff}, @code{rtag},
|
|||
|
|
@code{status}, @code{tag}, and @code{update}.
|
|||
|
|
|
|||
|
|
@cindex Editor, avoiding invocation of
|
|||
|
|
@cindex Avoiding editor invocation
|
|||
|
|
@item -m @var{message}
|
|||
|
|
Use @var{message} as log information, instead of
|
|||
|
|
invoking an editor.
|
|||
|
|
|
|||
|
|
Available with the following commands: @code{add},
|
|||
|
|
@code{commit} and @code{import}.
|
|||
|
|
|
|||
|
|
@item -n
|
|||
|
|
Do not run any checkout/commit/tag program. (A program can be
|
|||
|
|
specified to run on each of these activities, in the modules
|
|||
|
|
database (@pxref{modules}); this option bypasses it).
|
|||
|
|
|
|||
|
|
@strong{Warning:} this is not the same as the overall @samp{cvs -n}
|
|||
|
|
option, which you can specify to the left of a cvs command!
|
|||
|
|
|
|||
|
|
Available with the @code{checkout}, @code{commit}, @code{export},
|
|||
|
|
and @code{rtag} commands.
|
|||
|
|
|
|||
|
|
@item -P
|
|||
|
|
Prune (remove) directories that are empty after being updated, on
|
|||
|
|
@code{checkout}, or @code{update}. Normally, an empty directory
|
|||
|
|
(one that is void of revision-controlled files) is left alone.
|
|||
|
|
Specifying @samp{-P} will cause these directories to be silently
|
|||
|
|
removed from your checked-out sources. This does not remove the
|
|||
|
|
directory from the repository, only from your checked out copy.
|
|||
|
|
Note that this option is implied by the @samp{-r} or @samp{-D}
|
|||
|
|
options of @code{checkout} and @code{export}.
|
|||
|
|
@c -- implied--
|
|||
|
|
|
|||
|
|
@item -p
|
|||
|
|
Pipe the files retrieved from the repository to standard output,
|
|||
|
|
rather than writing them in the current directory. Available
|
|||
|
|
with the @code{checkout} and @code{update} commands.
|
|||
|
|
|
|||
|
|
@item -W
|
|||
|
|
Specify file names that should be filtered. You can
|
|||
|
|
use this option repeatedly. The spec can be a file
|
|||
|
|
name pattern of the same type that you can specify in
|
|||
|
|
the @file{.cvswrappers} file.
|
|||
|
|
Avaliable with the following commands: @code{import},
|
|||
|
|
and @code{update}.
|
|||
|
|
|
|||
|
|
@item -r @var{tag}
|
|||
|
|
Use the revision specified by the @var{tag} argument instead of the
|
|||
|
|
default @dfn{head} revision. As well as arbitrary tags defined
|
|||
|
|
with the @code{tag} or @code{rtag} command, two special tags are
|
|||
|
|
always available: @samp{HEAD} refers to the most recent version
|
|||
|
|
available in the repository, and @samp{BASE} refers to the
|
|||
|
|
revision you last checked out into the current working directory.
|
|||
|
|
|
|||
|
|
The tag specification is sticky when you use this option
|
|||
|
|
with @code{checkout} or @code{update} to make your own
|
|||
|
|
copy of a file: @sc{cvs} remembers the tag and continues to use it on
|
|||
|
|
future update commands, until you specify otherwise (for more information
|
|||
|
|
on sticky tags/dates, @pxref{Sticky tags}). The
|
|||
|
|
tag can be either a symbolic or numeric tag.
|
|||
|
|
@xref{Tags}.
|
|||
|
|
|
|||
|
|
Specifying the @samp{-q} global option along with the
|
|||
|
|
@samp{-r} command option is often useful, to suppress
|
|||
|
|
the warning messages when the @sc{rcs} history file
|
|||
|
|
does not contain the specified tag.
|
|||
|
|
|
|||
|
|
@strong{Warning:} this is not the same as the overall `cvs -r' option,
|
|||
|
|
which you can specify to the left of a cvs command!
|
|||
|
|
|
|||
|
|
@samp{-r} is available with the @code{checkout}, @code{commit},
|
|||
|
|
@code{diff}, @code{history}, @code{export}, @code{rdiff},
|
|||
|
|
@code{rtag}, and @code{update} commands.
|
|||
|
|
|
|||
|
|
@end table
|
|||
|
|
|
|||
|
|
@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
|
|||
|
|
@node add
|
|||
|
|
@appendixsec add---Add a new file/directory to the repository
|
|||
|
|
@cindex Add (subcommand)
|
|||
|
|
|
|||
|
|
@itemize @bullet
|
|||
|
|
@item
|
|||
|
|
Synopsis: add [-k kflag] [-m 'message'] files@dots{}
|
|||
|
|
@item
|
|||
|
|
Requires: repository, working directory.
|
|||
|
|
@item
|
|||
|
|
Changes: working directory.
|
|||
|
|
@item
|
|||
|
|
Synonym: new
|
|||
|
|
@end itemize
|
|||
|
|
|
|||
|
|
Use the @code{add} command to create a new file or directory in the
|
|||
|
|
source repository. The files or directories specified with @code{add}
|
|||
|
|
must already exist in the current directory (which must have been
|
|||
|
|
created with the @code{checkout} command). To add a whole new directory
|
|||
|
|
hierarchy to the source repository (for example, files received
|
|||
|
|
from a third-party vendor), use the @code{import} command
|
|||
|
|
instead. @xref{import}.
|
|||
|
|
|
|||
|
|
If the argument to @code{add} refers to an immediate
|
|||
|
|
sub-directory, the directory is created at the correct place in
|
|||
|
|
the source repository, and the necessary @sc{cvs} administration
|
|||
|
|
files are created in your working directory. If the directory
|
|||
|
|
already exists in the source repository, @code{add} still creates
|
|||
|
|
the administration files in your version of the directory.
|
|||
|
|
This allows you to use @code{add} to add a particular directory
|
|||
|
|
to your private sources even if someone else created that
|
|||
|
|
directory after your checkout of the sources. You can do the
|
|||
|
|
following:
|
|||
|
|
|
|||
|
|
@example
|
|||
|
|
$ mkdir new_directory
|
|||
|
|
$ cvs add new_directory
|
|||
|
|
$ cvs update new_directory
|
|||
|
|
@end example
|
|||
|
|
|
|||
|
|
An alternate approach using @code{update} might be:
|
|||
|
|
|
|||
|
|
@example
|
|||
|
|
$ cvs update -d new_directory
|
|||
|
|
@end example
|
|||
|
|
|
|||
|
|
(To add any available new directories to your working directory,
|
|||
|
|
it's probably simpler to use @code{checkout} (@pxref{checkout})
|
|||
|
|
or @samp{update -d} (@pxref{update})).
|
|||
|
|
|
|||
|
|
The added files are not placed in the source repository until you
|
|||
|
|
use @code{commit} to make the change permanent. Doing an
|
|||
|
|
@code{add} on a file that was removed with the @code{remove}
|
|||
|
|
command will resurrect the file, unless a @code{commit} command
|
|||
|
|
intervened.
|
|||
|
|
@xref{Removing files}, for an example.
|
|||
|
|
|
|||
|
|
|
|||
|
|
Unlike most other commands @code{add} never recurses down
|
|||
|
|
directories. It cannot yet handle relative paths. Instead of
|
|||
|
|
|
|||
|
|
@example
|
|||
|
|
$ cvs add foo/bar.c
|
|||
|
|
@end example
|
|||
|
|
|
|||
|
|
you have to do
|
|||
|
|
|
|||
|
|
@example
|
|||
|
|
$ cd foo
|
|||
|
|
$ cvs add bar.c
|
|||
|
|
@end example
|
|||
|
|
|
|||
|
|
@menu
|
|||
|
|
* add options:: add options
|
|||
|
|
* add examples:: add examples
|
|||
|
|
@end menu
|
|||
|
|
|
|||
|
|
@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
|
|||
|
|
@node add options
|
|||
|
|
@appendixsubsec add options
|
|||
|
|
@cindex Add options
|
|||
|
|
|
|||
|
|
There are only two options you can give to @samp{add}:
|
|||
|
|
|
|||
|
|
@table @code
|
|||
|
|
@item -k @var{kflag}
|
|||
|
|
This option specifies the default way that this file
|
|||
|
|
will be checked out. The @var{kflag} argument
|
|||
|
|
(@pxref{Substitution modes}) is stored in the @sc{rcs}
|
|||
|
|
file and can be changed with @code{admin -k}
|
|||
|
|
(@pxref{admin options}). See @ref{Binary files}, for
|
|||
|
|
information on using this option for binary files.
|
|||
|
|
|
|||
|
|
@item -m @var{description}
|
|||
|
|
Using this option, you can give a description for the file. This
|
|||
|
|
description appears in the history log (if it is enabled,
|
|||
|
|
@pxref{history file}). It will also be saved in the @sc{rcs} history
|
|||
|
|
file inside the repository when the file is committed. The
|
|||
|
|
@code{log} command displays this description.
|
|||
|
|
|
|||
|
|
The description can be changed using @samp{admin -t}.
|
|||
|
|
@xref{admin}.
|
|||
|
|
|
|||
|
|
If you omit the @samp{-m @var{description}} flag, an empty string will be
|
|||
|
|
used. You will not be prompted for a description.
|
|||
|
|
@end table
|
|||
|
|
|
|||
|
|
@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
|
|||
|
|
@node add examples
|
|||
|
|
@appendixsubsec add examples
|
|||
|
|
|
|||
|
|
To add the file @file{backend.c} to the repository, with a
|
|||
|
|
description, the following can be used.
|
|||
|
|
|
|||
|
|
@example
|
|||
|
|
$ cvs add -m "Optimizer and code generation passes." backend.c
|
|||
|
|
$ cvs commit -m "Early version. Not yet compilable." backend.c
|
|||
|
|
@end example
|
|||
|
|
|
|||
|
|
@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
|
|||
|
|
@node admin
|
|||
|
|
@appendixsec admin---Administration front end for rcs
|
|||
|
|
@cindex Admin (subcommand)
|
|||
|
|
|
|||
|
|
@itemize @bullet
|
|||
|
|
@item
|
|||
|
|
Requires: repository, working directory.
|
|||
|
|
@item
|
|||
|
|
Changes: repository.
|
|||
|
|
@item
|
|||
|
|
Synonym: rcs
|
|||
|
|
@end itemize
|
|||
|
|
|
|||
|
|
This is the @sc{cvs} interface to assorted administrative @sc{rcs}
|
|||
|
|
facilities, documented in rcs(1). @code{admin} simply passes
|
|||
|
|
all its options and arguments to the @code{rcs} command; it does
|
|||
|
|
no filtering or other processing. This command @emph{does} work
|
|||
|
|
recursively, however, so extreme care should be used.
|
|||
|
|
|
|||
|
|
If there is a group whose name matches a compiled in
|
|||
|
|
value which defaults to @code{cvsadmin}, only members
|
|||
|
|
of that group can use @code{cvs admin}. To disallow
|
|||
|
|
@code{cvs admin} for all users, create a group with no
|
|||
|
|
users in it.
|
|||
|
|
|
|||
|
|
@menu
|
|||
|
|
* admin options:: admin options
|
|||
|
|
* admin examples:: admin examples
|
|||
|
|
@end menu
|
|||
|
|
|
|||
|
|
@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
|
|||
|
|
@node admin options
|
|||
|
|
@appendixsubsec admin options
|
|||
|
|
|
|||
|
|
Not all valid @code{rcs} options are useful together
|
|||
|
|
with @sc{cvs}. Some even makes it impossible to use
|
|||
|
|
@sc{cvs} until you undo the effect!
|
|||
|
|
|
|||
|
|
This description of the available options is based on
|
|||
|
|
the @samp{rcs(1)} man page, but modified to suit
|
|||
|
|
readers that are more interrested in @sc{cvs} than
|
|||
|
|
@sc{rcs}.
|
|||
|
|
|
|||
|
|
@table @code
|
|||
|
|
@item -A@var{oldfile}
|
|||
|
|
Might not work together with @sc{cvs}. Append the
|
|||
|
|
access list of @var{oldfile} to the access list of the
|
|||
|
|
@sc{rcs} file.
|
|||
|
|
|
|||
|
|
@item -a@var{logins}
|
|||
|
|
Might not work together with @sc{cvs}. Append the
|
|||
|
|
login names appearing in the comma-separated list
|
|||
|
|
@var{logins} to the access list of the @sc{rcs} file.
|
|||
|
|
|
|||
|
|
@item -b[@var{rev}]
|
|||
|
|
When used with bare @sc{rcs}, this
|
|||
|
|
option sets the default branch to @var{rev}; in
|
|||
|
|
@sc{cvs} sticky tags (@pxref{Sticky tags}) are a better
|
|||
|
|
way to decide which branch you want to work on. With
|
|||
|
|
@sc{cvs}, this option can be used to control behavior
|
|||
|
|
with respect to the vendor branch.
|
|||
|
|
@c FIXME: document how you use it with the vendor
|
|||
|
|
@c branch (or fix cvs so that there is a more graceful
|
|||
|
|
@c way to handle the case).
|
|||
|
|
|
|||
|
|
@item -c@var{string}
|
|||
|
|
Useful with @sc{cvs}. Sets the comment leader to
|
|||
|
|
@var{string}. The comment leader is printed before
|
|||
|
|
every log message line generated by the keyword
|
|||
|
|
@code{$@asis{}Log$} (@pxref{Keyword substitution}).
|
|||
|
|
This is useful for programming languages without
|
|||
|
|
multi-line comments. @sc{Rcs} initially guesses the
|
|||
|
|
value of the comment leader from the file name
|
|||
|
|
extension when the file is first committed.
|
|||
|
|
|
|||
|
|
@item -e[@var{logins}]
|
|||
|
|
Might not work together with @sc{cvs}. Erase the login
|
|||
|
|
names appearing in the comma-separated list
|
|||
|
|
@var{logins} from the access list of the RCS file. If
|
|||
|
|
@var{logins} is omitted, erase the entire access list.
|
|||
|
|
|
|||
|
|
@item -I
|
|||
|
|
Run interactively, even if the standard input is not a
|
|||
|
|
terminal.
|
|||
|
|
|
|||
|
|
@item -i
|
|||
|
|
Useless with @sc{cvs}. When using bare @sc{rcs}, this
|
|||
|
|
is used to create and initialize a new @sc{rcs} file,
|
|||
|
|
without depositing a revision.
|
|||
|
|
|
|||
|
|
@item -k@var{subst}
|
|||
|
|
Useful with @sc{cvs}. Set the default keyword
|
|||
|
|
substitution to @var{subst}. @xref{Keyword
|
|||
|
|
substitution}. Giving an explicit @samp{-k} option to
|
|||
|
|
@code{cvs update}, @code{cvs export}, or @code{cvs
|
|||
|
|
checkout} overrides this default.
|
|||
|
|
|
|||
|
|
@cindex Reserved checkouts
|
|||
|
|
@cindex RCS-style locking
|
|||
|
|
@item -l[@var{rev}]
|
|||
|
|
Lock the revision with number @var{rev}. If a branch
|
|||
|
|
is given, lock the latest revision on that branch. If
|
|||
|
|
@var{rev} is omitted, lock the latest revision on the
|
|||
|
|
default branch.
|
|||
|
|
|
|||
|
|
This can be used in conjunction with the
|
|||
|
|
@file{rcslock.pl} script in the @file{contrib}
|
|||
|
|
directory of the @sc{cvs} source distribution to
|
|||
|
|
provide reserved checkouts (where only one user can be
|
|||
|
|
editing a given file at a time). See the comments in
|
|||
|
|
that file for details (and see the @file{README} file
|
|||
|
|
in that directory for disclaimers about the unsupported
|
|||
|
|
nature of contrib). According to comments in that
|
|||
|
|
file, locking must set to strict (which is the default).
|
|||
|
|
|
|||
|
|
@item -L
|
|||
|
|
Set locking to strict. Strict locking means that the
|
|||
|
|
owner of an RCS file is not exempt from locking for
|
|||
|
|
checkin. For use with @sc{cvs}, strict locking must be
|
|||
|
|
set; see the discussion under the @samp{-l} option above.
|
|||
|
|
|
|||
|
|
@cindex Changing a log message
|
|||
|
|
@cindex Replacing a log message
|
|||
|
|
@cindex Correcting a log message
|
|||
|
|
@cindex Fixing a log message
|
|||
|
|
@cindex Log message, correcting
|
|||
|
|
@item -m@var{rev}:@var{msg}
|
|||
|
|
Replace the log message of revision @var{rev} with
|
|||
|
|
@var{msg}.
|
|||
|
|
|
|||
|
|
@item -N@var{name}[:[@var{rev}]]
|
|||
|
|
Act like @samp{-n}, except override any previous
|
|||
|
|
assignment of @var{name}.
|
|||
|
|
|
|||
|
|
@item -n@var{name}[:[@var{rev}]]
|
|||
|
|
Associate the symbolic name @var{name} with the branch
|
|||
|
|
or revision @var{rev}. It is normally better to use
|
|||
|
|
@samp{cvs tag} or @samp{cvs rtag} instead. Delete the
|
|||
|
|
symbolic name if both @samp{:} and @var{rev} are
|
|||
|
|
omitted; otherwise, print an error message if
|
|||
|
|
@var{name} is already associated with another number.
|
|||
|
|
If @var{rev} is symbolic, it is expanded before
|
|||
|
|
association. A @var{rev} consisting of a branch number
|
|||
|
|
followed by a @samp{.} stands for the current latest
|
|||
|
|
revision in the branch. A @samp{:} with an empty
|
|||
|
|
@var{rev} stands for the current latest revision on the
|
|||
|
|
default branch, normally the trunk. For example,
|
|||
|
|
@samp{rcs -n@var{name}: RCS/*} associates @var{name} with the
|
|||
|
|
current latest revision of all the named RCS files;
|
|||
|
|
this contrasts with @samp{rcs -n@var{name}:$ RCS/*} which
|
|||
|
|
associates @var{name} with the revision numbers
|
|||
|
|
extracted from keyword strings in the corresponding
|
|||
|
|
working files.
|
|||
|
|
|
|||
|
|
@cindex Deleting revisions
|
|||
|
|
@cindex Outdating revisions
|
|||
|
|
@cindex Saving space
|
|||
|
|
@item -o@var{range}
|
|||
|
|
Potentially useful, but dangerous, with @sc{cvs} (see below).
|
|||
|
|
Deletes (@dfn{outdates}) the revisions given by
|
|||
|
|
@var{range}. A range consisting of a single revision
|
|||
|
|
number means that revision. A range consisting of a
|
|||
|
|
branch number means the latest revision on that branch.
|
|||
|
|
A range of the form @samp{@var{rev1}:@var{rev2}} means
|
|||
|
|
revisions @var{rev1} to @var{rev2} on the same branch,
|
|||
|
|
@samp{:@var{rev}} means from the beginning of the
|
|||
|
|
branch containing @var{rev} up to and including
|
|||
|
|
@var{rev}, and @samp{@var{rev}:} means from revision
|
|||
|
|
@var{rev} to the end of the branch containing
|
|||
|
|
@var{rev}. None of the outdated revisions may have
|
|||
|
|
branches or locks.
|
|||
|
|
|
|||
|
|
Due to the way @sc{cvs} handles branches @var{rev}
|
|||
|
|
cannot be specified symbolically if it is a branch.
|
|||
|
|
@xref{Magic branch numbers}, for an explanation.
|
|||
|
|
|
|||
|
|
Make sure that no-one has checked out a copy of the
|
|||
|
|
revision you outdate. Strange things will happen if he
|
|||
|
|
starts to edit it and tries to check it back in. For
|
|||
|
|
this reason, this option is not a good way to take back
|
|||
|
|
a bogus commit; commit a new revision undoing the bogus
|
|||
|
|
change instead (@pxref{Merging two revisions}).
|
|||
|
|
|
|||
|
|
@item -q
|
|||
|
|
Run quietly; do not print diagnostics.
|
|||
|
|
|
|||
|
|
@item -s@var{state}[:@var{rev}]
|
|||
|
|
Useful with @sc{cvs}. Set the state attribute of the
|
|||
|
|
revision @var{rev} to @var{state}. If @var{rev} is a
|
|||
|
|
branch number, assume the latest revision on that
|
|||
|
|
branch. If @var{rev} is omitted, assume the latest
|
|||
|
|
revision on the default branch. Any identifier is
|
|||
|
|
acceptable for @var{state}. A useful set of states is
|
|||
|
|
@samp{Exp} (for experimental), @samp{Stab} (for
|
|||
|
|
stable), and @samp{Rel} (for released). By default,
|
|||
|
|
the state of a new revision is set to @samp{Exp} when
|
|||
|
|
it is created. The state is visible in the output from
|
|||
|
|
@var{cvs log} (@pxref{log}), and in the
|
|||
|
|
@samp{$@asis{}Log$} and @samp{$@asis{}State$} keywords
|
|||
|
|
(@pxref{Keyword substitution}). Note that @sc{cvs}
|
|||
|
|
uses the @code{dead} state for its own purposes; to
|
|||
|
|
take a file to or from the @code{dead} state use
|
|||
|
|
commands like @code{cvs remove} and @code{cvs add}, not
|
|||
|
|
@code{cvs admin -s}.
|
|||
|
|
|
|||
|
|
@item -t[@var{file}]
|
|||
|
|
Useful with @sc{cvs}. Write descriptive text from the
|
|||
|
|
contents of the named @var{file} into the RCS file,
|
|||
|
|
deleting the existing text. The @var{file} pathname
|
|||
|
|
may not begin with @samp{-}. If @var{file} is omitted,
|
|||
|
|
obtain the text from standard input, terminated by
|
|||
|
|
end-of-file or by a line containing @samp{.} by itself.
|
|||
|
|
Prompt for the text if interaction is possible; see
|
|||
|
|
@samp{-I}. The descriptive text can be seen in the
|
|||
|
|
output from @samp{cvs log} (@pxref{log}).
|
|||
|
|
|
|||
|
|
@item -t-@var{string}
|
|||
|
|
Similar to @samp{-t@var{file}}. Write descriptive text
|
|||
|
|
from the @var{string} into the @sc{rcs} file, deleting
|
|||
|
|
the existing text.
|
|||
|
|
|
|||
|
|
@item -U
|
|||
|
|
Set locking to non-strict. Non-strict locking means
|
|||
|
|
that the owner of a file need not lock a revision for
|
|||
|
|
checkin. For use with @sc{cvs}, strict locking must be
|
|||
|
|
set; see the discussion under the @samp{-l} option
|
|||
|
|
above.
|
|||
|
|
|
|||
|
|
@item -u[@var{rev}]
|
|||
|
|
See the option @samp{-l} above, for a discussion of
|
|||
|
|
using this option with @sc{cvs}. Unlock the revision
|
|||
|
|
with number @var{rev}. If a branch is given, unlock
|
|||
|
|
the latest revision on that branch. If @var{rev} is
|
|||
|
|
omitted, remove the latest lock held by the caller.
|
|||
|
|
Normally, only the locker of a revision may unlock it.
|
|||
|
|
Somebody else unlocking a revision breaks the lock.
|
|||
|
|
This causes a mail message to be sent to the original
|
|||
|
|
locker. The message contains a commentary solicited
|
|||
|
|
from the breaker. The commentary is terminated by
|
|||
|
|
end-of-file or by a line containing @code{.} by itself.
|
|||
|
|
|
|||
|
|
@item -V@var{n}
|
|||
|
|
Emulate @sc{rcs} version @var{n}. Use -V@var{n} to make
|
|||
|
|
an @sc{rcs} file acceptable to @sc{rcs} version @var{n}
|
|||
|
|
by discarding information that would confuse version
|
|||
|
|
@var{n}.
|
|||
|
|
|
|||
|
|
@item -x@var{suffixes}
|
|||
|
|
Useless with @sc{cvs}. Use @var{suffixes} to
|
|||
|
|
characterize RCS files.
|
|||
|
|
@end table
|
|||
|
|
|
|||
|
|
|
|||
|
|
@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
|
|||
|
|
@node admin examples
|
|||
|
|
@appendixsubsec admin examples
|
|||
|
|
|
|||
|
|
@appendixsubsubsec Outdating is dangerous
|
|||
|
|
|
|||
|
|
First, an example of how @emph{not} to use the
|
|||
|
|
@code{admin} command. It is included to stress the
|
|||
|
|
fact that this command can be quite dangerous unless
|
|||
|
|
you know @emph{exactly} what you are doing.
|
|||
|
|
|
|||
|
|
The @samp{-o} option can be used to @dfn{outdate} old revisions
|
|||
|
|
from the history file. If you are short on disc this option
|
|||
|
|
might help you. But think twice before using it---there is no
|
|||
|
|
way short of restoring the latest backup to undo this command!
|
|||
|
|
|
|||
|
|
The next line is an example of a command that you would
|
|||
|
|
@emph{not} like to execute.
|
|||
|
|
|
|||
|
|
@example
|
|||
|
|
$ cvs admin -o:R_1_02 .
|
|||
|
|
@end example
|
|||
|
|
|
|||
|
|
The above command will delete all revisions up to, and
|
|||
|
|
including, the revision that corresponds to the tag
|
|||
|
|
R_1_02. But beware! If there are files that have not
|
|||
|
|
changed between R_1_02 and R_1_03 the file will have
|
|||
|
|
@emph{the same} numerical revision number assigned to
|
|||
|
|
the tags R_1_02 and R_1_03. So not only will it be
|
|||
|
|
impossible to retrieve R_1_02; R_1_03 will also have to
|
|||
|
|
be restored from the tapes!
|
|||
|
|
|
|||
|
|
@appendixsubsubsec Comment leaders
|
|||
|
|
@cindex Comment leader
|
|||
|
|
@cindex Log keyword, selecting comment leader
|
|||
|
|
@cindex Nroff (selecting comment leader)
|
|||
|
|
|
|||
|
|
If you use the @code{$@asis{}Log$} keyword and you do
|
|||
|
|
not agree with the guess for comment leader that
|
|||
|
|
@sc{cvs} has done, you can enforce your will with
|
|||
|
|
@code{cvs admin -c}. This might be suitable for
|
|||
|
|
@code{nroff} source:
|
|||
|
|
|
|||
|
|
@example
|
|||
|
|
$ cvs admin -c'.\" ' *.man
|
|||
|
|
$ rm *.man
|
|||
|
|
$ cvs update
|
|||
|
|
@end example
|
|||
|
|
|
|||
|
|
The two last steps are to make sure that you get the
|
|||
|
|
versions with correct comment leaders in your working
|
|||
|
|
files.
|
|||
|
|
|
|||
|
|
@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
|
|||
|
|
@node checkout
|
|||
|
|
@appendixsec checkout---Check out sources for editing
|
|||
|
|
@cindex Checkout (subcommand)
|
|||
|
|
@cindex Co (subcommand)
|
|||
|
|
|
|||
|
|
@itemize @bullet
|
|||
|
|
@item
|
|||
|
|
Synopsis: checkout [options] modules@dots{}
|
|||
|
|
@item
|
|||
|
|
Requires: repository.
|
|||
|
|
@item
|
|||
|
|
Changes: working directory.
|
|||
|
|
@item
|
|||
|
|
Synonyms: co, get
|
|||
|
|
@end itemize
|
|||
|
|
|
|||
|
|
Make a working directory containing copies of the
|
|||
|
|
source files specified by @var{modules}. You must execute
|
|||
|
|
@code{checkout} before using most of the other @sc{cvs}
|
|||
|
|
commands, since most of them operate on your working
|
|||
|
|
directory.
|
|||
|
|
|
|||
|
|
The @var{modules} part of the command are either
|
|||
|
|
symbolic names for some
|
|||
|
|
collection of source directories and files, or paths to
|
|||
|
|
directories or files in the repository. The symbolic
|
|||
|
|
names are defined in the @samp{modules} file.
|
|||
|
|
@xref{modules}.
|
|||
|
|
|
|||
|
|
Depending on the modules you specify, @code{checkout} may
|
|||
|
|
recursively create directories and populate them with
|
|||
|
|
the appropriate source files. You can then edit these
|
|||
|
|
source files at any time (regardless of whether other
|
|||
|
|
software developers are editing their own copies of the
|
|||
|
|
sources); update them to include new changes applied by
|
|||
|
|
others to the source repository; or commit your work as
|
|||
|
|
a permanent change to the source repository.
|
|||
|
|
|
|||
|
|
Note that @code{checkout} is used to create
|
|||
|
|
directories. The top-level directory created is always
|
|||
|
|
added to the directory where @code{checkout} is
|
|||
|
|
invoked, and usually has the same name as the specified
|
|||
|
|
module. In the case of a module alias, the created
|
|||
|
|
sub-directory may have a different name, but you can be
|
|||
|
|
sure that it will be a sub-directory, and that
|
|||
|
|
@code{checkout} will show the relative path leading to
|
|||
|
|
each file as it is extracted into your private work
|
|||
|
|
area (unless you specify the @samp{-Q} global option).
|
|||
|
|
|
|||
|
|
The files created by @code{checkout} are created
|
|||
|
|
read-write, unless the @samp{-r} option to @sc{cvs}
|
|||
|
|
(@pxref{Global options}) is specified, the
|
|||
|
|
@code{CVSREAD} environment variable is specified
|
|||
|
|
(@pxref{Environment variables}), or a watch is in
|
|||
|
|
effect for that file (@pxref{Watches}).
|
|||
|
|
|
|||
|
|
@c FIXME: misleading--checkout takes a module as
|
|||
|
|
@c argument, and update does not--so -d behavior is not the only
|
|||
|
|
@c difference.
|
|||
|
|
Running @code{checkout} on a directory that was already
|
|||
|
|
built by a prior @code{checkout} is also permitted, and
|
|||
|
|
has the same effect as specifying the @samp{-d} option
|
|||
|
|
to the @code{update} command, that is, any new
|
|||
|
|
directories that have been created in the repository
|
|||
|
|
will appear in your work area. @xref{update}.
|
|||
|
|
|
|||
|
|
@menu
|
|||
|
|
* checkout options:: checkout options
|
|||
|
|
* checkout examples:: checkout examples
|
|||
|
|
@end menu
|
|||
|
|
|
|||
|
|
@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
|
|||
|
|
@node checkout options
|
|||
|
|
@appendixsubsec checkout options
|
|||
|
|
|
|||
|
|
These standard options are supported by @code{checkout}
|
|||
|
|
(@pxref{Common options}, for a complete description of
|
|||
|
|
them):
|
|||
|
|
|
|||
|
|
@table @code
|
|||
|
|
@item -D @var{date}
|
|||
|
|
Use the most recent revision no later than @var{date}.
|
|||
|
|
This option is sticky, and implies @samp{-P}. See
|
|||
|
|
@ref{Sticky tags}, for more information on sticky tags/dates.
|
|||
|
|
|
|||
|
|
@item -f
|
|||
|
|
Only useful with the @samp{-D @var{date}} or @samp{-r
|
|||
|
|
@var{tag}} flags. If no matching revision is found,
|
|||
|
|
retrieve the most recent revision (instead of ignoring
|
|||
|
|
the file).
|
|||
|
|
|
|||
|
|
@item -k @var{kflag}
|
|||
|
|
Process @sc{rcs} keywords according to @var{kflag}. See
|
|||
|
|
co(1). This option is sticky; future updates of
|
|||
|
|
this file in this working directory will use the same
|
|||
|
|
@var{kflag}. The @code{status} command can be viewed
|
|||
|
|
to see the sticky options. @xref{status}.
|
|||
|
|
|
|||
|
|
@item -l
|
|||
|
|
Local; run only in current working directory.
|
|||
|
|
|
|||
|
|
@item -n
|
|||
|
|
Do not run any checkout program (as specified
|
|||
|
|
with the @samp{-o} option in the modules file;
|
|||
|
|
@pxref{modules}).
|
|||
|
|
|
|||
|
|
@item -P
|
|||
|
|
Prune empty directories.
|
|||
|
|
|
|||
|
|
@item -p
|
|||
|
|
Pipe files to the standard output.
|
|||
|
|
|
|||
|
|
@item -r @var{tag}
|
|||
|
|
Use revision @var{tag}. This option is sticky, and implies @samp{-P}.
|
|||
|
|
See @ref{Sticky tags}, for more information on sticky tags/dates.
|
|||
|
|
@end table
|
|||
|
|
|
|||
|
|
In addition to those, you can use these special command
|
|||
|
|
options with @code{checkout}:
|
|||
|
|
|
|||
|
|
@table @code
|
|||
|
|
@item -A
|
|||
|
|
Reset any sticky tags, dates, or @samp{-k} options.
|
|||
|
|
See @ref{Sticky tags}, for more information on sticky tags/dates.
|
|||
|
|
|
|||
|
|
@item -c
|
|||
|
|
Copy the module file, sorted, to the standard output,
|
|||
|
|
instead of creating or modifying any files or
|
|||
|
|
directories in your working directory.
|
|||
|
|
|
|||
|
|
@item -d @var{dir}
|
|||
|
|
Create a directory called @var{dir} for the working
|
|||
|
|
files, instead of using the module name. Unless you
|
|||
|
|
also use @samp{-N}, the paths created under @var{dir}
|
|||
|
|
will be as short as possible.
|
|||
|
|
|
|||
|
|
@item -j @var{tag}
|
|||
|
|
With two @samp{-j} options, merge changes from the
|
|||
|
|
revision specified with the first @samp{-j} option to
|
|||
|
|
the revision specified with the second @samp{j} option,
|
|||
|
|
into the working directory.
|
|||
|
|
|
|||
|
|
With one @samp{-j} option, merge changes from the
|
|||
|
|
ancestor revision to the revision specified with the
|
|||
|
|
@samp{-j} option, into the working directory. The
|
|||
|
|
ancestor revision is the common ancestor of the
|
|||
|
|
revision which the working directory is based on, and
|
|||
|
|
the revision specified in the @samp{-j} option.
|
|||
|
|
|
|||
|
|
In addition, each -j option can contain an optional
|
|||
|
|
date specification which, when used with branches, can
|
|||
|
|
limit the chosen revision to one within a specific
|
|||
|
|
date. An optional date is specified by adding a colon
|
|||
|
|
(:) to the tag:
|
|||
|
|
@samp{-j@var{Symbolic_Tag}:@var{Date_Specifier}}.
|
|||
|
|
|
|||
|
|
@xref{Merging}.
|
|||
|
|
|
|||
|
|
@item -N
|
|||
|
|
Only useful together with @samp{-d @var{dir}}. With this
|
|||
|
|
option, @sc{cvs} will not shorten module paths in your
|
|||
|
|
working directory. (Normally, @sc{cvs} shortens paths as
|
|||
|
|
much as possible when you specify an explicit target
|
|||
|
|
directory).
|
|||
|
|
|
|||
|
|
@item -s
|
|||
|
|
Like @samp{-c}, but include the status of all modules,
|
|||
|
|
and sort it by the status string. @xref{modules}, for
|
|||
|
|
info about the @samp{-s} option that is used inside the
|
|||
|
|
modules file to set the module status.
|
|||
|
|
@end table
|
|||
|
|
|
|||
|
|
@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
|
|||
|
|
@node checkout examples
|
|||
|
|
@appendixsubsec checkout examples
|
|||
|
|
|
|||
|
|
Get a copy of the module @samp{tc}:
|
|||
|
|
|
|||
|
|
@example
|
|||
|
|
$ cvs checkout tc
|
|||
|
|
@end example
|
|||
|
|
|
|||
|
|
Get a copy of the module @samp{tc} as it looked one day
|
|||
|
|
ago:
|
|||
|
|
|
|||
|
|
@example
|
|||
|
|
$ cvs checkout -D yesterday tc
|
|||
|
|
@end example
|
|||
|
|
|
|||
|
|
@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
|
|||
|
|
@node commit
|
|||
|
|
@appendixsec commit---Check files into the repository
|
|||
|
|
@cindex Commit (subcommand)
|
|||
|
|
|
|||
|
|
@itemize @bullet
|
|||
|
|
@item
|
|||
|
|
Version 1.3 Synopsis: commit [-lnR] [-m 'log_message' |
|
|||
|
|
-f file] [-r revision] [files@dots{}]
|
|||
|
|
@item
|
|||
|
|
Version 1.3.1 Synopsis: commit [-lnRf] [-m 'log_message' |
|
|||
|
|
-F file] [-r revision] [files@dots{}]
|
|||
|
|
@c -- rename-f-F--
|
|||
|
|
@item
|
|||
|
|
Requires: working directory, repository.
|
|||
|
|
@item
|
|||
|
|
Changes: repository.
|
|||
|
|
@item
|
|||
|
|
Synonym: ci
|
|||
|
|
@end itemize
|
|||
|
|
|
|||
|
|
@strong{Warning:} The @samp{-f @var{file}} option will
|
|||
|
|
probably be renamed to @samp{-F @var{file}}, and @samp{-f}
|
|||
|
|
will be given a new behavior in future releases of @sc{cvs}.
|
|||
|
|
@c -- rename-f-F--
|
|||
|
|
|
|||
|
|
Use @code{commit} when you want to incorporate changes
|
|||
|
|
from your working source files into the source
|
|||
|
|
repository.
|
|||
|
|
|
|||
|
|
If you don't specify particular files to commit, all of
|
|||
|
|
the files in your working current directory are
|
|||
|
|
examined. @code{commit} is careful to change in the
|
|||
|
|
repository only those files that you have really
|
|||
|
|
changed. By default (or if you explicitly specify the
|
|||
|
|
@samp{-R} option), files in subdirectories are also
|
|||
|
|
examined and committed if they have changed; you can
|
|||
|
|
use the @samp{-l} option to limit @code{commit} to the
|
|||
|
|
current directory only.
|
|||
|
|
|
|||
|
|
@code{commit} verifies that the selected files are up
|
|||
|
|
to date with the current revisions in the source
|
|||
|
|
repository; it will notify you, and exit without
|
|||
|
|
committing, if any of the specified files must be made
|
|||
|
|
current first with @code{update} (@pxref{update}).
|
|||
|
|
@code{commit} does not call the @code{update} command
|
|||
|
|
for you, but rather leaves that for you to do when the
|
|||
|
|
time is right.
|
|||
|
|
|
|||
|
|
When all is well, an editor is invoked to allow you to
|
|||
|
|
enter a log message that will be written to one or more
|
|||
|
|
logging programs (@pxref{modules}, and @pxref{loginfo})
|
|||
|
|
and placed in the @sc{rcs} history file inside the
|
|||
|
|
repository. This log message can be retrieved with the
|
|||
|
|
@code{log} command; @xref{log}. You can specify the
|
|||
|
|
log message on the command line with the @samp{-m
|
|||
|
|
@var{message}} option, and thus avoid the editor invocation,
|
|||
|
|
or use the @samp{-f @var{file}} option to specify
|
|||
|
|
@c -- rename-f-F--
|
|||
|
|
that the argument file contains the log message.
|
|||
|
|
|
|||
|
|
@menu
|
|||
|
|
* commit options:: commit options
|
|||
|
|
* commit examples:: commit examples
|
|||
|
|
@end menu
|
|||
|
|
|
|||
|
|
@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
|
|||
|
|
@node commit options
|
|||
|
|
@appendixsubsec commit options
|
|||
|
|
|
|||
|
|
These standard options are supported by @code{commit}
|
|||
|
|
(@pxref{Common options}, for a complete description of
|
|||
|
|
them):
|
|||
|
|
|
|||
|
|
@table @code
|
|||
|
|
@item -l
|
|||
|
|
Local; run only in current working directory.
|
|||
|
|
|
|||
|
|
@item -n
|
|||
|
|
Do not run any module program.
|
|||
|
|
|
|||
|
|
@item -R
|
|||
|
|
Commit directories recursively. This is on by default.
|
|||
|
|
|
|||
|
|
@item -r @var{revision}
|
|||
|
|
Commit to @var{revision}. @var{revision} must be
|
|||
|
|
either a branch, or a revision on the main trunk that
|
|||
|
|
is higher than any existing revision number. You
|
|||
|
|
cannot commit to a specific revision on a branch.
|
|||
|
|
@end table
|
|||
|
|
|
|||
|
|
@code{commit} also supports these options:
|
|||
|
|
|
|||
|
|
@table @code
|
|||
|
|
@item -F @var{file}
|
|||
|
|
This option is present in @sc{cvs} releases 1.3-s3 and
|
|||
|
|
later. Read the log message from @var{file}, instead
|
|||
|
|
of invoking an editor.
|
|||
|
|
|
|||
|
|
@item -f
|
|||
|
|
@c -- rename-f-F--
|
|||
|
|
This option is present in @sc{cvs} 1.3-s3 and later releases
|
|||
|
|
of @sc{cvs}. Note that this is not the standard behavior of
|
|||
|
|
the @samp{-f} option as defined in @xref{Common options}.
|
|||
|
|
|
|||
|
|
Force @sc{cvs} to commit a new revision even if you haven't
|
|||
|
|
made any changes to the file. If the current revision
|
|||
|
|
of @var{file} is 1.7, then the following two commands
|
|||
|
|
are equivalent:
|
|||
|
|
|
|||
|
|
@example
|
|||
|
|
$ cvs commit -f @var{file}
|
|||
|
|
$ cvs commit -r 1.8 @var{file}
|
|||
|
|
@end example
|
|||
|
|
|
|||
|
|
@item -f @var{file}
|
|||
|
|
@c -- rename-f-F--
|
|||
|
|
This option is present in @sc{cvs} releases 1.3, 1.3-s1 and
|
|||
|
|
1.3-s2. Note that this is not the standard behavior of
|
|||
|
|
the @samp{-f} option as defined in @xref{Common options}.
|
|||
|
|
|
|||
|
|
Read the log message from @var{file}, instead
|
|||
|
|
of invoking an editor.
|
|||
|
|
|
|||
|
|
@item -m @var{message}
|
|||
|
|
Use @var{message} as the log message, instead of
|
|||
|
|
invoking an editor.
|
|||
|
|
@end table
|
|||
|
|
|
|||
|
|
@need 2000
|
|||
|
|
@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
|
|||
|
|
@node commit examples
|
|||
|
|
@appendixsubsec commit examples
|
|||
|
|
|
|||
|
|
@appendixsubsubsec New major release number
|
|||
|
|
|
|||
|
|
When you make a major release of your product, you
|
|||
|
|
might want the revision numbers to track your major
|
|||
|
|
release number. You should normally not care about
|
|||
|
|
the revision numbers, but this is a thing that many
|
|||
|
|
people want to do, and it can be done without doing any
|
|||
|
|
harm.
|
|||
|
|
|
|||
|
|
To bring all your files up to the @sc{rcs} revision 3.0
|
|||
|
|
(including those that haven't changed), you might do:
|
|||
|
|
|
|||
|
|
@example
|
|||
|
|
$ cvs commit -r 3.0
|
|||
|
|
@end example
|
|||
|
|
|
|||
|
|
Note that it is generally a bad idea to try to make the
|
|||
|
|
@sc{rcs} revision number equal to the current release number
|
|||
|
|
of your product. You should think of the revision
|
|||
|
|
number as an internal number that the @sc{cvs} package
|
|||
|
|
maintains, and that you generally never need to care
|
|||
|
|
much about. Using the @code{tag} and @code{rtag}
|
|||
|
|
commands you can give symbolic names to the releases
|
|||
|
|
instead. @xref{tag} and @xref{rtag}.
|
|||
|
|
|
|||
|
|
Note that the number you specify with @samp{-r} must be
|
|||
|
|
larger than any existing revision number. That is, if
|
|||
|
|
revision 3.0 exists, you cannot @samp{cvs commit
|
|||
|
|
-r 1.3}.
|
|||
|
|
|
|||
|
|
@appendixsubsubsec Committing to a branch
|
|||
|
|
|
|||
|
|
You can commit to a branch revision (one that has an
|
|||
|
|
even number of dots) with the @samp{-r} option. To
|
|||
|
|
create a branch revision, use the @samp{-b} option
|
|||
|
|
of the @code{rtag} or @code{tag} commands (@pxref{tag}
|
|||
|
|
or @pxref{rtag}). Then, either @code{checkout} or
|
|||
|
|
@code{update} can be used to base your sources on the
|
|||
|
|
newly created branch. From that point on, all
|
|||
|
|
@code{commit} changes made within these working sources
|
|||
|
|
will be automatically added to a branch revision,
|
|||
|
|
thereby not disturbing main-line development in any
|
|||
|
|
way. For example, if you had to create a patch to the
|
|||
|
|
1.2 version of the product, even though the 2.0 version
|
|||
|
|
is already under development, you might do:
|
|||
|
|
|
|||
|
|
@example
|
|||
|
|
$ cvs rtag -b -r FCS1_2 FCS1_2_Patch product_module
|
|||
|
|
$ cvs checkout -r FCS1_2_Patch product_module
|
|||
|
|
$ cd product_module
|
|||
|
|
[[ hack away ]]
|
|||
|
|
$ cvs commit
|
|||
|
|
@end example
|
|||
|
|
|
|||
|
|
@noindent
|
|||
|
|
This works automatically since the @samp{-r} option is
|
|||
|
|
sticky.
|
|||
|
|
|
|||
|
|
@appendixsubsubsec Creating the branch after editing
|
|||
|
|
|
|||
|
|
Say you have been working on some extremely
|
|||
|
|
experimental software, based on whatever revision you
|
|||
|
|
happened to checkout last week. If others in your
|
|||
|
|
group would like to work on this software with you, but
|
|||
|
|
without disturbing main-line development, you could
|
|||
|
|
commit your change to a new branch. Others can then
|
|||
|
|
checkout your experimental stuff and utilize the full
|
|||
|
|
benefit of @sc{cvs} conflict resolution. The scenario might
|
|||
|
|
look like:
|
|||
|
|
|
|||
|
|
@c FIXME: Should we be recommending tagging the branchpoint?
|
|||
|
|
@example
|
|||
|
|
[[ hacked sources are present ]]
|
|||
|
|
$ cvs tag -b EXPR1
|
|||
|
|
$ cvs update -r EXPR1
|
|||
|
|
$ cvs commit
|
|||
|
|
@end example
|
|||
|
|
|
|||
|
|
The @code{update} command will make the @samp{-r
|
|||
|
|
EXPR1} option sticky on all files. Note that your
|
|||
|
|
changes to the files will never be removed by the
|
|||
|
|
@code{update} command. The @code{commit} will
|
|||
|
|
automatically commit to the correct branch, because the
|
|||
|
|
@samp{-r} is sticky. You could also do like this:
|
|||
|
|
|
|||
|
|
@c FIXME: Should we be recommending tagging the branchpoint?
|
|||
|
|
@example
|
|||
|
|
[[ hacked sources are present ]]
|
|||
|
|
$ cvs tag -b EXPR1
|
|||
|
|
$ cvs commit -r EXPR1
|
|||
|
|
@end example
|
|||
|
|
|
|||
|
|
@noindent
|
|||
|
|
but then, only those files that were changed by you
|
|||
|
|
will have the @samp{-r EXPR1} sticky flag. If you hack
|
|||
|
|
away, and commit without specifying the @samp{-r EXPR1}
|
|||
|
|
flag, some files may accidentally end up on the main
|
|||
|
|
trunk.
|
|||
|
|
|
|||
|
|
To work with you on the experimental change, others
|
|||
|
|
would simply do
|
|||
|
|
|
|||
|
|
@example
|
|||
|
|
$ cvs checkout -r EXPR1 whatever_module
|
|||
|
|
@end example
|
|||
|
|
|
|||
|
|
@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
|
|||
|
|
@node diff
|
|||
|
|
@appendixsec diff---Run diffs between revisions
|
|||
|
|
@cindex Diff (subcommand)
|
|||
|
|
|
|||
|
|
@itemize @bullet
|
|||
|
|
@item
|
|||
|
|
Synopsis: diff [-l] [rcsdiff_options] [[-r rev1 | -D date1] [-r rev2 | -D date2]] [files@dots{}]
|
|||
|
|
@item
|
|||
|
|
Requires: working directory, repository.
|
|||
|
|
@item
|
|||
|
|
Changes: nothing.
|
|||
|
|
@end itemize
|
|||
|
|
|
|||
|
|
The @code{diff} command is used to compare different
|
|||
|
|
revisions of files. The default action is to compare
|
|||
|
|
your working files with the revisions they were based
|
|||
|
|
on, and report any differences that are found.
|
|||
|
|
|
|||
|
|
If any file names are given, only those files are
|
|||
|
|
compared. If any directories are given, all files
|
|||
|
|
under them will be compared.
|
|||
|
|
|
|||
|
|
The exit status will be 0 if no differences were found,
|
|||
|
|
1 if some differences were found, and 2 if any error
|
|||
|
|
occurred.
|
|||
|
|
|
|||
|
|
@menu
|
|||
|
|
* diff options:: diff options
|
|||
|
|
* diff examples:: diff examples
|
|||
|
|
@end menu
|
|||
|
|
|
|||
|
|
@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
|
|||
|
|
@node diff options
|
|||
|
|
@appendixsubsec diff options
|
|||
|
|
|
|||
|
|
These standard options are supported by @code{diff}
|
|||
|
|
(@pxref{Common options}, for a complete description of
|
|||
|
|
them):
|
|||
|
|
|
|||
|
|
@table @code
|
|||
|
|
@item -D @var{date}
|
|||
|
|
Use the most recent revision no later than @var{date}.
|
|||
|
|
See @samp{-r} for how this affects the comparison.
|
|||
|
|
|
|||
|
|
@sc{cvs} can be configured to pass the @samp{-D} option
|
|||
|
|
through to @code{rcsdiff} (which in turn passes it on
|
|||
|
|
to @code{diff}. @sc{Gnu} diff uses @samp{-D} as a way to
|
|||
|
|
put @code{cpp}-style @samp{#define} statements around the output
|
|||
|
|
differences. There is no way short of testing to
|
|||
|
|
figure out how @sc{cvs} was configured. In the default
|
|||
|
|
configuration @sc{cvs} will use the @samp{-D @var{date}} option.
|
|||
|
|
|
|||
|
|
@item -k @var{kflag}
|
|||
|
|
Process @sc{rcs} keywords according to @var{kflag}. See
|
|||
|
|
co(1).
|
|||
|
|
|
|||
|
|
@item -l
|
|||
|
|
Local; run only in current working directory.
|
|||
|
|
|
|||
|
|
@item -R
|
|||
|
|
Examine directories recursively. This option is on by
|
|||
|
|
default.
|
|||
|
|
|
|||
|
|
@item -r @var{tag}
|
|||
|
|
Compare with revision @var{tag}. Zero, one or two
|
|||
|
|
@samp{-r} options can be present. With no @samp{-r}
|
|||
|
|
option, the working file will be compared with the
|
|||
|
|
revision it was based on. With one @samp{-r}, that
|
|||
|
|
revision will be compared to your current working file.
|
|||
|
|
With two @samp{-r} options those two revisions will be
|
|||
|
|
compared (and your working file will not affect the
|
|||
|
|
outcome in any way).
|
|||
|
|
|
|||
|
|
One or both @samp{-r} options can be replaced by a
|
|||
|
|
@samp{-D @var{date}} option, described above.
|
|||
|
|
@end table
|
|||
|
|
|
|||
|
|
Any other options that are found are passed through to
|
|||
|
|
@code{rcsdiff}, which in turn passes them to
|
|||
|
|
@code{diff}. The exact meaning of the options depends
|
|||
|
|
on which @code{diff} you are using. The long options
|
|||
|
|
introduced in @sc{gnu} diff 2.0 are not yet supported in
|
|||
|
|
@sc{cvs}. See the documentation for your @code{diff} to see
|
|||
|
|
which options are supported.
|
|||
|
|
|
|||
|
|
@c -- Document some common useful diff options, such as
|
|||
|
|
@c -u and -c.
|
|||
|
|
@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
|
|||
|
|
@node diff examples
|
|||
|
|
@appendixsubsec diff examples
|
|||
|
|
|
|||
|
|
The following line produces a Unidiff (@samp{-u} flag)
|
|||
|
|
between revision 1.14 and 1.19 of
|
|||
|
|
@file{backend.c}. Due to the @samp{-kk} flag no
|
|||
|
|
keywords are substituted, so differences that only depend
|
|||
|
|
on keyword substitution are ignored.
|
|||
|
|
|
|||
|
|
@example
|
|||
|
|
$ cvs diff -kk -u -r 1.14 -r 1.19 backend.c
|
|||
|
|
@end example
|
|||
|
|
|
|||
|
|
Suppose the experimental branch EXPR1 was based on a
|
|||
|
|
set of files tagged RELEASE_1_0. To see what has
|
|||
|
|
happened on that branch, the following can be used:
|
|||
|
|
|
|||
|
|
@example
|
|||
|
|
$ cvs diff -r RELEASE_1_0 -r EXPR1
|
|||
|
|
@end example
|
|||
|
|
|
|||
|
|
A command like this can be used to produce a context
|
|||
|
|
diff between two releases:
|
|||
|
|
|
|||
|
|
@example
|
|||
|
|
$ cvs diff -c -r RELEASE_1_0 -r RELEASE_1_1 > diffs
|
|||
|
|
@end example
|
|||
|
|
|
|||
|
|
If you are maintaining ChangeLogs, a command like the following
|
|||
|
|
just before you commit your changes may help you write
|
|||
|
|
the ChangeLog entry. All local modifications that have
|
|||
|
|
not yet been committed will be printed.
|
|||
|
|
|
|||
|
|
@example
|
|||
|
|
$ cvs diff -u | less
|
|||
|
|
@end example
|
|||
|
|
|
|||
|
|
@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
|
|||
|
|
@node export
|
|||
|
|
@appendixsec export---Export sources from CVS, similar to checkout
|
|||
|
|
@cindex Export (subcommand)
|
|||
|
|
|
|||
|
|
@itemize @bullet
|
|||
|
|
@item
|
|||
|
|
Synopsis: export [-flNn] [-r rev|-D date] [-k subst] [-d dir] module@dots{}
|
|||
|
|
@item
|
|||
|
|
Requires: repository.
|
|||
|
|
@item
|
|||
|
|
Changes: current directory.
|
|||
|
|
@end itemize
|
|||
|
|
|
|||
|
|
This command is a variant of @code{checkout}; use it
|
|||
|
|
when you want a copy of the source for module without
|
|||
|
|
the @sc{cvs} administrative directories. For example, you
|
|||
|
|
might use @code{export} to prepare source for shipment
|
|||
|
|
off-site. This command requires that you specify a
|
|||
|
|
date or tag (with @samp{-D} or @samp{-r}), so that you
|
|||
|
|
can count on reproducing the source you ship to others.
|
|||
|
|
|
|||
|
|
One often would like to use @samp{-kv} with @code{cvs
|
|||
|
|
export}. This causes any @sc{rcs} keywords to be
|
|||
|
|
expanded such that an import done at some other site
|
|||
|
|
will not lose the keyword revision information. But be
|
|||
|
|
aware that doesn't handle an export containing binary
|
|||
|
|
files correctly. Also be aware that after having used
|
|||
|
|
@samp{-kv}, one can no longer use the @code{ident}
|
|||
|
|
command (which is part of the @sc{rcs} suite---see
|
|||
|
|
ident(1)) which looks for @sc{rcs} keyword strings. If
|
|||
|
|
you want to be able to use @code{ident} you must not
|
|||
|
|
use @samp{-kv}.
|
|||
|
|
|
|||
|
|
@menu
|
|||
|
|
* export options:: export options
|
|||
|
|
@end menu
|
|||
|
|
|
|||
|
|
@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
|
|||
|
|
@node export options
|
|||
|
|
@appendixsubsec export options
|
|||
|
|
|
|||
|
|
These standard options are supported by @code{export}
|
|||
|
|
(@pxref{Common options}, for a complete description of
|
|||
|
|
them):
|
|||
|
|
|
|||
|
|
@table @code
|
|||
|
|
@item -D @var{date}
|
|||
|
|
Use the most recent revision no later than @var{date}.
|
|||
|
|
|
|||
|
|
@item -f
|
|||
|
|
If no matching revision is found, retrieve the most
|
|||
|
|
recent revision (instead of ignoring the file).
|
|||
|
|
|
|||
|
|
@item -l
|
|||
|
|
Local; run only in current working directory.
|
|||
|
|
|
|||
|
|
@item -n
|
|||
|
|
Do not run any checkout program.
|
|||
|
|
|
|||
|
|
@item -R
|
|||
|
|
Export directories recursively. This is on by default.
|
|||
|
|
|
|||
|
|
@item -r @var{tag}
|
|||
|
|
Use revision @var{tag}.
|
|||
|
|
@end table
|
|||
|
|
|
|||
|
|
In addition, these options (that are common to
|
|||
|
|
@code{checkout} and @code{export}) are also supported:
|
|||
|
|
|
|||
|
|
@table @code
|
|||
|
|
@item -d @var{dir}
|
|||
|
|
Create a directory called @var{dir} for the working
|
|||
|
|
files, instead of using the module name. Unless you
|
|||
|
|
also use @samp{-N}, the paths created under @var{dir}
|
|||
|
|
will be as short as possible.
|
|||
|
|
|
|||
|
|
@item -k @var{subst}
|
|||
|
|
Set keyword expansion mode (@pxref{Substitution modes}).
|
|||
|
|
|
|||
|
|
@item -N
|
|||
|
|
Only useful together with @samp{-d @var{dir}}. With this
|
|||
|
|
option, @sc{cvs} will not shorten module paths in your
|
|||
|
|
working directory. (Normally, @sc{cvs} shortens paths as
|
|||
|
|
much as possible when you specify an explicit target
|
|||
|
|
directory.)
|
|||
|
|
@end table
|
|||
|
|
|
|||
|
|
@ignore
|
|||
|
|
@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
|
|||
|
|
@c @node export examples
|
|||
|
|
@appendixsubsec export examples
|
|||
|
|
|
|||
|
|
Contributed examples are gratefully accepted.
|
|||
|
|
@c -- Examples here!!
|
|||
|
|
@end ignore
|
|||
|
|
|
|||
|
|
@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
|
|||
|
|
@node history
|
|||
|
|
@appendixsec history---Show status of files and users
|
|||
|
|
@cindex History (subcommand)
|
|||
|
|
|
|||
|
|
@itemize @bullet
|
|||
|
|
@item
|
|||
|
|
Synopsis: history [-report] [-flags] [-options args] [files@dots{}]
|
|||
|
|
@item
|
|||
|
|
Requires: the file @file{$CVSROOT/CVSROOT/history}
|
|||
|
|
@item
|
|||
|
|
Changes: nothing.
|
|||
|
|
@end itemize
|
|||
|
|
|
|||
|
|
@sc{cvs} can keep a history file that tracks each use of the
|
|||
|
|
@code{checkout}, @code{commit}, @code{rtag},
|
|||
|
|
@code{update}, and @code{release} commands. You can
|
|||
|
|
use @code{history} to display this information in
|
|||
|
|
various formats.
|
|||
|
|
|
|||
|
|
Logging must be enabled by creating the file
|
|||
|
|
@file{$CVSROOT/CVSROOT/history}.
|
|||
|
|
|
|||
|
|
@strong{Warning:} @code{history} uses @samp{-f}, @samp{-l},
|
|||
|
|
@samp{-n}, and @samp{-p} in ways that conflict with the
|
|||
|
|
normal use inside @sc{cvs} (@pxref{Common options}).
|
|||
|
|
|
|||
|
|
@menu
|
|||
|
|
* history options:: history options
|
|||
|
|
@end menu
|
|||
|
|
|
|||
|
|
@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
|
|||
|
|
@node history options
|
|||
|
|
@appendixsubsec history options
|
|||
|
|
|
|||
|
|
Several options (shown above as @samp{-report}) control what
|
|||
|
|
kind of report is generated:
|
|||
|
|
|
|||
|
|
@table @code
|
|||
|
|
@item -c
|
|||
|
|
Report on each time commit was used (i.e., each time
|
|||
|
|
the repository was modified).
|
|||
|
|
|
|||
|
|
@item -e
|
|||
|
|
Everything (all record types); equivalent to specifying
|
|||
|
|
@samp{-xMACFROGWUT}.
|
|||
|
|
|
|||
|
|
@item -m @var{module}
|
|||
|
|
Report on a particular module. (You can meaningfully
|
|||
|
|
use @samp{-m} more than once on the command line.)
|
|||
|
|
|
|||
|
|
@item -o
|
|||
|
|
Report on checked-out modules.
|
|||
|
|
|
|||
|
|
@item -T
|
|||
|
|
Report on all tags.
|
|||
|
|
|
|||
|
|
@item -x @var{type}
|
|||
|
|
Extract a particular set of record types @var{type} from the @sc{cvs}
|
|||
|
|
history. The types are indicated by single letters,
|
|||
|
|
which you may specify in combination.
|
|||
|
|
|
|||
|
|
Certain commands have a single record type:
|
|||
|
|
|
|||
|
|
@table @code
|
|||
|
|
@item F
|
|||
|
|
release
|
|||
|
|
@item O
|
|||
|
|
checkout
|
|||
|
|
@item T
|
|||
|
|
rtag
|
|||
|
|
@end table
|
|||
|
|
|
|||
|
|
@noindent
|
|||
|
|
One of four record types may result from an update:
|
|||
|
|
|
|||
|
|
@table @code
|
|||
|
|
@item C
|
|||
|
|
A merge was necessary but collisions were
|
|||
|
|
detected (requiring manual merging).
|
|||
|
|
@item G
|
|||
|
|
A merge was necessary and it succeeded.
|
|||
|
|
@item U
|
|||
|
|
A working file was copied from the repository.
|
|||
|
|
@item W
|
|||
|
|
The working copy of a file was deleted during
|
|||
|
|
update (because it was gone from the repository).
|
|||
|
|
@end table
|
|||
|
|
|
|||
|
|
@noindent
|
|||
|
|
One of three record types results from commit:
|
|||
|
|
|
|||
|
|
@table @code
|
|||
|
|
@item A
|
|||
|
|
A file was added for the first time.
|
|||
|
|
@item M
|
|||
|
|
A file was modified.
|
|||
|
|
@item R
|
|||
|
|
A file was removed.
|
|||
|
|
@end table
|
|||
|
|
@end table
|
|||
|
|
|
|||
|
|
The options shown as @samp{-flags} constrain or expand
|
|||
|
|
the report without requiring option arguments:
|
|||
|
|
|
|||
|
|
@table @code
|
|||
|
|
@item -a
|
|||
|
|
Show data for all users (the default is to show data
|
|||
|
|
only for the user executing @code{history}).
|
|||
|
|
|
|||
|
|
@item -l
|
|||
|
|
Show last modification only.
|
|||
|
|
|
|||
|
|
@item -w
|
|||
|
|
Show only the records for modifications done from the
|
|||
|
|
same working directory where @code{history} is
|
|||
|
|
executing.
|
|||
|
|
@end table
|
|||
|
|
|
|||
|
|
The options shown as @samp{-options @var{args}} constrain the report
|
|||
|
|
based on an argument:
|
|||
|
|
|
|||
|
|
@table @code
|
|||
|
|
@item -b @var{str}
|
|||
|
|
Show data back to a record containing the string
|
|||
|
|
@var{str} in either the module name, the file name, or
|
|||
|
|
the repository path.
|
|||
|
|
|
|||
|
|
@item -D @var{date}
|
|||
|
|
Show data since @var{date}. This is slightly different
|
|||
|
|
from the normal use of @samp{-D @var{date}}, which
|
|||
|
|
selects the newest revision older than @var{date}.
|
|||
|
|
|
|||
|
|
@item -p @var{repository}
|
|||
|
|
Show data for a particular source repository (you
|
|||
|
|
can specify several @samp{-p} options on the same command
|
|||
|
|
line).
|
|||
|
|
|
|||
|
|
@item -r @var{rev}
|
|||
|
|
Show records referring to revisions since the revision
|
|||
|
|
or tag named @var{rev} appears in individual @sc{rcs}
|
|||
|
|
files. Each @sc{rcs} file is searched for the revision or
|
|||
|
|
tag.
|
|||
|
|
|
|||
|
|
@item -t @var{tag}
|
|||
|
|
Show records since tag @var{tag} was last added to the the
|
|||
|
|
history file. This differs from the @samp{-r} flag
|
|||
|
|
above in that it reads only the history file, not the
|
|||
|
|
@sc{rcs} files, and is much faster.
|
|||
|
|
|
|||
|
|
@item -u @var{name}
|
|||
|
|
Show records for user @var{name}.
|
|||
|
|
@end table
|
|||
|
|
|
|||
|
|
@ignore
|
|||
|
|
@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
|
|||
|
|
@c @node history examples
|
|||
|
|
@appendixsubsec history examples
|
|||
|
|
|
|||
|
|
Contributed examples will gratefully be accepted.
|
|||
|
|
@c -- Examples here!
|
|||
|
|
@end ignore
|
|||
|
|
|
|||
|
|
@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
|
|||
|
|
@node import
|
|||
|
|
@appendixsec import---Import sources into CVS, using vendor branches
|
|||
|
|
@cindex Import (subcommand)
|
|||
|
|
|
|||
|
|
@itemize @bullet
|
|||
|
|
@item
|
|||
|
|
Synopsis: import [-options] repository vendortag releasetag@dots{}
|
|||
|
|
@item
|
|||
|
|
Requires: Repository, source distribution directory.
|
|||
|
|
@item
|
|||
|
|
Changes: repository.
|
|||
|
|
@end itemize
|
|||
|
|
|
|||
|
|
Use @code{import} to incorporate an entire source
|
|||
|
|
distribution from an outside source (e.g., a source
|
|||
|
|
vendor) into your source repository directory. You can
|
|||
|
|
use this command both for initial creation of a
|
|||
|
|
repository, and for wholesale updates to the module
|
|||
|
|
from the outside source. @xref{Tracking sources}, for
|
|||
|
|
a discussion on this subject.
|
|||
|
|
|
|||
|
|
The @var{repository} argument gives a directory name
|
|||
|
|
(or a path to a directory) under the @sc{cvs} root directory
|
|||
|
|
for repositories; if the directory did not exist,
|
|||
|
|
import creates it.
|
|||
|
|
|
|||
|
|
When you use import for updates to source that has been
|
|||
|
|
modified in your source repository (since a prior
|
|||
|
|
import), it will notify you of any files that conflict
|
|||
|
|
in the two branches of development; use @samp{checkout
|
|||
|
|
-j} to reconcile the differences, as import instructs
|
|||
|
|
you to do.
|
|||
|
|
|
|||
|
|
If @sc{cvs} decides a file should be ignored
|
|||
|
|
(@pxref{cvsignore}), it does not import it and prints
|
|||
|
|
@samp{I } followed by the filename
|
|||
|
|
|
|||
|
|
If the file @file{$CVSROOT/CVSROOT/cvswrappers} exists,
|
|||
|
|
any file whose names match the specifications in that
|
|||
|
|
file will be treated as packages and the appropriate
|
|||
|
|
filtering will be performed on the file/directory
|
|||
|
|
before being imported, @xref{Wrappers}.
|
|||
|
|
|
|||
|
|
The outside source is saved in a first-level @sc{rcs}
|
|||
|
|
branch, by default 1.1.1. Updates are leaves of this
|
|||
|
|
branch; for example, files from the first imported
|
|||
|
|
collection of source will be revision 1.1.1.1, then
|
|||
|
|
files from the first imported update will be revision
|
|||
|
|
1.1.1.2, and so on.
|
|||
|
|
|
|||
|
|
At least three arguments are required.
|
|||
|
|
@var{repository} is needed to identify the collection
|
|||
|
|
of source. @var{vendortag} is a tag for the entire
|
|||
|
|
branch (e.g., for 1.1.1). You must also specify at
|
|||
|
|
least one @var{releasetag} to identify the files at
|
|||
|
|
the leaves created each time you execute @code{import}.
|
|||
|
|
|
|||
|
|
@menu
|
|||
|
|
* import options:: import options
|
|||
|
|
* import examples:: import examples
|
|||
|
|
@end menu
|
|||
|
|
|
|||
|
|
@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
|
|||
|
|
@node import options
|
|||
|
|
@appendixsubsec import options
|
|||
|
|
|
|||
|
|
This standard option is supported by @code{import}
|
|||
|
|
(@pxref{Common options}, for a complete description):
|
|||
|
|
|
|||
|
|
@table @code
|
|||
|
|
@item -m @var{message}
|
|||
|
|
Use @var{message} as log information, instead of
|
|||
|
|
invoking an editor.
|
|||
|
|
@end table
|
|||
|
|
|
|||
|
|
There are three additional special options.
|
|||
|
|
|
|||
|
|
@table @code
|
|||
|
|
@item -b @var{branch}
|
|||
|
|
Specify a first-level branch other than 1.1.1. Unless
|
|||
|
|
the @samp{-b @var{branch}} flag is given, revisions will
|
|||
|
|
@emph{always} be made to the branch 1.1.1---even if a
|
|||
|
|
@var{vendortag} that matches another branch is given!
|
|||
|
|
What happens in that case, is that the tag will be
|
|||
|
|
reset to 1.1.1. Warning: This behavior might change
|
|||
|
|
in the future.
|
|||
|
|
|
|||
|
|
@item -k @var{subst}
|
|||
|
|
Indicate the RCS keyword expansion mode desired. This
|
|||
|
|
setting will apply to all files created during the
|
|||
|
|
import, but not to any files that previously existed in
|
|||
|
|
the repository. See @ref{Substitution modes} for a
|
|||
|
|
list of valid @samp{-k} settings.
|
|||
|
|
|
|||
|
|
@item -I @var{name}
|
|||
|
|
Specify file names that should be ignored during
|
|||
|
|
import. You can use this option repeatedly. To avoid
|
|||
|
|
ignoring any files at all (even those ignored by
|
|||
|
|
default), specify `-I !'.
|
|||
|
|
|
|||
|
|
@var{name} can be a file name pattern of the same type
|
|||
|
|
that you can specify in the @file{.cvsignore} file.
|
|||
|
|
@xref{cvsignore}.
|
|||
|
|
@c -- Is this really true?
|
|||
|
|
|
|||
|
|
@item -W @var{spec}
|
|||
|
|
Specify file names that should be filtered during
|
|||
|
|
import. You can use this option repeatedly.
|
|||
|
|
|
|||
|
|
@var{spec} can be a file name pattern of the same type
|
|||
|
|
that you can specify in the @file{.cvswrappers}
|
|||
|
|
file. @xref{Wrappers}.
|
|||
|
|
@end table
|
|||
|
|
|
|||
|
|
@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
|
|||
|
|
@node import examples
|
|||
|
|
@appendixsubsec import examples
|
|||
|
|
|
|||
|
|
@xref{Tracking sources}, and @xref{From files}.
|
|||
|
|
|
|||
|
|
@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
|
|||
|
|
@node log
|
|||
|
|
@appendixsec log---Print out 'rlog' information for files
|
|||
|
|
@cindex Log (subcommand)
|
|||
|
|
|
|||
|
|
@itemize @bullet
|
|||
|
|
@item
|
|||
|
|
Synopsis: log [-l] rlog-options [files@dots{}]
|
|||
|
|
@item
|
|||
|
|
Requires: repository, working directory.
|
|||
|
|
@item
|
|||
|
|
Changes: nothing.
|
|||
|
|
@item
|
|||
|
|
Synonym: rlog
|
|||
|
|
@end itemize
|
|||
|
|
|
|||
|
|
Display log information for files. @code{log} calls
|
|||
|
|
the @sc{rcs} utility @code{rlog}, which prints all available
|
|||
|
|
information about the @sc{rcs} history file. This includes
|
|||
|
|
the location of the @sc{rcs} file, the @dfn{head} revision
|
|||
|
|
(the latest revision on the trunk), all symbolic names (tags)
|
|||
|
|
and some other things. For each revision, the revision
|
|||
|
|
number, the author, the number of lines added/deleted and
|
|||
|
|
the log message are printed. All times are displayed in
|
|||
|
|
Coordinated Universal Time (UTC). (Other parts of @sc{cvs}
|
|||
|
|
print times in the local timezone).
|
|||
|
|
@c -- timezone--
|
|||
|
|
|
|||
|
|
@menu
|
|||
|
|
* log options:: log options
|
|||
|
|
* log examples:: log examples
|
|||
|
|
@end menu
|
|||
|
|
|
|||
|
|
@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
|
|||
|
|
@node log options
|
|||
|
|
@appendixsubsec log options
|
|||
|
|
|
|||
|
|
Only one option is interpreted by @sc{cvs} and not passed on to @code{rlog}:
|
|||
|
|
|
|||
|
|
@table @code
|
|||
|
|
@item -l
|
|||
|
|
Local; run only in current working directory. (Default
|
|||
|
|
is to run recursively).
|
|||
|
|
@end table
|
|||
|
|
|
|||
|
|
By default, @code{rlog} prints all information that is
|
|||
|
|
available. All other options (including those that
|
|||
|
|
normally behave differently) are passed through to
|
|||
|
|
@code{rlog} and restrict the output. See rlog(1) for a
|
|||
|
|
complete description of options. This incomplete list
|
|||
|
|
(which is a slightly edited extract from rlog(1)) lists
|
|||
|
|
all options that are useful in conjunction with @sc{cvs}.
|
|||
|
|
|
|||
|
|
@strong{Please note:} There can be no space between the option
|
|||
|
|
and its argument, since @code{rlog} parses its options
|
|||
|
|
in a different way than @sc{cvs}.
|
|||
|
|
|
|||
|
|
@table @code
|
|||
|
|
@item -b
|
|||
|
|
Print information about the revisions on the default
|
|||
|
|
branch, normally the highest branch on the trunk.
|
|||
|
|
|
|||
|
|
@item -d@var{dates}
|
|||
|
|
Print information about revisions with a checkin
|
|||
|
|
date/time in the range given by the
|
|||
|
|
semicolon-separated list of dates. The following table
|
|||
|
|
explains the available range formats:
|
|||
|
|
|
|||
|
|
@table @code
|
|||
|
|
@item @var{d1}<@var{d2}
|
|||
|
|
@itemx @var{d2}>@var{d1}
|
|||
|
|
Select the revisions that were deposited between
|
|||
|
|
@var{d1} and @var{d2} inclusive.
|
|||
|
|
|
|||
|
|
@item <@var{d}
|
|||
|
|
@itemx @var{d}>
|
|||
|
|
Select all revisions dated @var{d} or earlier.
|
|||
|
|
|
|||
|
|
@item @var{d}<
|
|||
|
|
@itemx >@var{d}
|
|||
|
|
Select all revisions dated @var{d} or later.
|
|||
|
|
|
|||
|
|
@item @var{d}
|
|||
|
|
Select the single, latest revision dated @var{d} or
|
|||
|
|
earlier.
|
|||
|
|
@end table
|
|||
|
|
|
|||
|
|
The date/time strings @var{d}, @var{d1}, and @var{d2}
|
|||
|
|
are in the free format explained in co(1). Quoting is
|
|||
|
|
normally necessary, especially for < and >. Note that
|
|||
|
|
the separator is a semicolon (;).
|
|||
|
|
|
|||
|
|
@item -h
|
|||
|
|
Print only the @sc{rcs} pathname, working pathname, head,
|
|||
|
|
default branch, access list, locks, symbolic names, and
|
|||
|
|
suffix.
|
|||
|
|
|
|||
|
|
@item -N
|
|||
|
|
Do not print the list of tags for this file. This
|
|||
|
|
option can be very useful when your site uses a lot of
|
|||
|
|
tags, so rather than "more"'ing over 3 pages of tag
|
|||
|
|
information, the log information is presented without
|
|||
|
|
tags at all.
|
|||
|
|
|
|||
|
|
@item -R
|
|||
|
|
Print only the name of the @sc{rcs} history file.
|
|||
|
|
|
|||
|
|
@item -r@var{revisions}
|
|||
|
|
Print information about revisions given in the
|
|||
|
|
comma-separated list @var{revisions} of revisions and
|
|||
|
|
ranges. The following table explains the available
|
|||
|
|
range formats:
|
|||
|
|
|
|||
|
|
@table @code
|
|||
|
|
@item @var{rev1}:@var{rev2}
|
|||
|
|
Revisions @var{rev1} to @var{rev2} (which must be on
|
|||
|
|
the same branch).
|
|||
|
|
|
|||
|
|
@item :@var{rev}
|
|||
|
|
Revisions from the beginning of the branch up to
|
|||
|
|
and including @var{rev}.
|
|||
|
|
|
|||
|
|
@item @var{rev}:
|
|||
|
|
Revisions starting with @var{rev} to the end of the
|
|||
|
|
branch containing @var{rev}.
|
|||
|
|
|
|||
|
|
@item @var{branch}
|
|||
|
|
An argument that is a branch means all revisions on
|
|||
|
|
that branch. You can unfortunately not specify a
|
|||
|
|
symbolic branch here. You must specify the numeric
|
|||
|
|
branch number. @xref{Magic branch numbers}, for an
|
|||
|
|
explanation.
|
|||
|
|
|
|||
|
|
@item @var{branch1}:@var{branch2}
|
|||
|
|
A range of branches means all revisions
|
|||
|
|
on the branches in that range.
|
|||
|
|
|
|||
|
|
@item @var{branch}.
|
|||
|
|
The latest revision in @var{branch}.
|
|||
|
|
@end table
|
|||
|
|
|
|||
|
|
A bare @samp{-r} with no revisions means the latest
|
|||
|
|
revision on the default branch, normally the trunk.
|
|||
|
|
|
|||
|
|
@item -s@var{states}
|
|||
|
|
Print information about revisions whose state
|
|||
|
|
attributes match one of the states given in the
|
|||
|
|
comma-separated list @var{states}.
|
|||
|
|
|
|||
|
|
@item -t
|
|||
|
|
Print the same as @samp{-h}, plus the descriptive text.
|
|||
|
|
|
|||
|
|
@item -w@var{logins}
|
|||
|
|
Print information about revisions checked in by users
|
|||
|
|
with login names appearing in the comma-separated list
|
|||
|
|
@var{logins}. If @var{logins} is omitted, the user's
|
|||
|
|
login is assumed.
|
|||
|
|
@end table
|
|||
|
|
|
|||
|
|
@code{rlog} prints the intersection of the revisions
|
|||
|
|
selected with the options @samp{-d}, @samp{-l},
|
|||
|
|
@samp{-s}, and @samp{-w}, intersected with the union of
|
|||
|
|
the revisions selected by @samp{-b} and @samp{-r}.
|
|||
|
|
|
|||
|
|
@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
|
|||
|
|
@node log examples
|
|||
|
|
@appendixsubsec log examples
|
|||
|
|
|
|||
|
|
Contributed examples are gratefully accepted.
|
|||
|
|
|
|||
|
|
@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
|
|||
|
|
@node rdiff
|
|||
|
|
@appendixsec rdiff---'patch' format diffs between releases
|
|||
|
|
@cindex Rdiff (subcommand)
|
|||
|
|
|
|||
|
|
@itemize @bullet
|
|||
|
|
@item
|
|||
|
|
rdiff [-flags] [-V vn] [-r t|-D d [-r t2|-D d2]] modules@dots{}
|
|||
|
|
@item
|
|||
|
|
Requires: repository.
|
|||
|
|
@item
|
|||
|
|
Changes: nothing.
|
|||
|
|
@item
|
|||
|
|
Synonym: patch
|
|||
|
|
@end itemize
|
|||
|
|
|
|||
|
|
Builds a Larry Wall format patch(1) file between two
|
|||
|
|
releases, that can be fed directly into the patch
|
|||
|
|
program to bring an old release up-to-date with the new
|
|||
|
|
release. (This is one of the few @sc{cvs} commands that
|
|||
|
|
operates directly from the repository, and doesn't
|
|||
|
|
require a prior checkout.) The diff output is sent to
|
|||
|
|
the standard output device.
|
|||
|
|
|
|||
|
|
You can specify (using the standard @samp{-r} and
|
|||
|
|
@samp{-D} options) any combination of one or two
|
|||
|
|
revisions or dates. If only one revision or date is
|
|||
|
|
specified, the patch file reflects differences between
|
|||
|
|
that revision or date and the current head revisions in
|
|||
|
|
the @sc{rcs} file.
|
|||
|
|
|
|||
|
|
Note that if the software release affected is contained
|
|||
|
|
in more than one directory, then it may be necessary to
|
|||
|
|
specify the @samp{-p} option to the patch command when
|
|||
|
|
patching the old sources, so that patch is able to find
|
|||
|
|
the files that are located in other directories.
|
|||
|
|
|
|||
|
|
@menu
|
|||
|
|
* rdiff options:: rdiff options
|
|||
|
|
* rdiff examples:: rdiff examples
|
|||
|
|
@end menu
|
|||
|
|
|
|||
|
|
@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
|
|||
|
|
@node rdiff options
|
|||
|
|
@appendixsubsec rdiff options
|
|||
|
|
|
|||
|
|
These standard options are supported by @code{rdiff}
|
|||
|
|
(@pxref{Common options}, for a complete description of
|
|||
|
|
them):
|
|||
|
|
|
|||
|
|
@table @code
|
|||
|
|
@item -D @var{date}
|
|||
|
|
Use the most recent revision no later than @var{date}.
|
|||
|
|
|
|||
|
|
@item -f
|
|||
|
|
If no matching revision is found, retrieve the most
|
|||
|
|
recent revision (instead of ignoring the file).
|
|||
|
|
|
|||
|
|
@item -l
|
|||
|
|
Local; don't descend subdirectories.
|
|||
|
|
|
|||
|
|
@item -r @var{tag}
|
|||
|
|
Use revision @var{tag}.
|
|||
|
|
@end table
|
|||
|
|
|
|||
|
|
In addition to the above, these options are available:
|
|||
|
|
|
|||
|
|
@table @code
|
|||
|
|
@item -c
|
|||
|
|
Use the context diff format. This is the default format.
|
|||
|
|
|
|||
|
|
@item -s
|
|||
|
|
Create a summary change report instead of a patch. The
|
|||
|
|
summary includes information about files that were
|
|||
|
|
changed or added between the releases. It is sent to
|
|||
|
|
the standard output device. This is useful for finding
|
|||
|
|
out, for example, which files have changed between two
|
|||
|
|
dates or revisions.
|
|||
|
|
|
|||
|
|
@item -t
|
|||
|
|
A diff of the top two revisions is sent to the standard
|
|||
|
|
output device. This is most useful for seeing what the
|
|||
|
|
last change to a file was.
|
|||
|
|
|
|||
|
|
@item -u
|
|||
|
|
Use the unidiff format for the context diffs.
|
|||
|
|
This option is not available if your diff does not
|
|||
|
|
support the unidiff format. Remember that old versions
|
|||
|
|
of the @code{patch} program can't handle the unidiff
|
|||
|
|
format, so if you plan to post this patch to the net
|
|||
|
|
you should probably not use @samp{-u}.
|
|||
|
|
|
|||
|
|
@item -V @var{vn}
|
|||
|
|
Expand @sc{rcs} keywords according to the rules current in
|
|||
|
|
@sc{rcs} version @var{vn} (the expansion format changed with
|
|||
|
|
@sc{rcs} version 5).
|
|||
|
|
@end table
|
|||
|
|
|
|||
|
|
@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
|
|||
|
|
@node rdiff examples
|
|||
|
|
@appendixsubsec rdiff examples
|
|||
|
|
|
|||
|
|
Suppose you receive mail from @t{foo@@bar.com} asking for an
|
|||
|
|
update from release 1.2 to 1.4 of the tc compiler. You
|
|||
|
|
have no such patches on hand, but with @sc{cvs} that can
|
|||
|
|
easily be fixed with a command such as this:
|
|||
|
|
|
|||
|
|
@example
|
|||
|
|
$ cvs rdiff -c -r FOO1_2 -r FOO1_4 tc | \
|
|||
|
|
$$ Mail -s 'The patches you asked for' foo@@bar.com
|
|||
|
|
@end example
|
|||
|
|
|
|||
|
|
Suppose you have made release 1.3, and forked a branch
|
|||
|
|
called @samp{R_1_3fix} for bugfixes. @samp{R_1_3_1}
|
|||
|
|
corresponds to release 1.3.1, which was made some time
|
|||
|
|
ago. Now, you want to see how much development has been
|
|||
|
|
done on the branch. This command can be used:
|
|||
|
|
|
|||
|
|
@example
|
|||
|
|
$ cvs patch -s -r R_1_3_1 -r R_1_3fix module-name
|
|||
|
|
cvs rdiff: Diffing module-name
|
|||
|
|
File ChangeLog,v changed from revision 1.52.2.5 to 1.52.2.6
|
|||
|
|
File foo.c,v changed from revision 1.52.2.3 to 1.52.2.4
|
|||
|
|
File bar.h,v changed from revision 1.29.2.1 to 1.2
|
|||
|
|
@end example
|
|||
|
|
|
|||
|
|
@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
|
|||
|
|
@node release
|
|||
|
|
@appendixsec release---Indicate that a Module is no longer in use
|
|||
|
|
@cindex Release (subcommand)
|
|||
|
|
|
|||
|
|
@itemize @bullet
|
|||
|
|
@item
|
|||
|
|
release [-d] directories@dots{}
|
|||
|
|
@item
|
|||
|
|
Requires: Working directory.
|
|||
|
|
@item
|
|||
|
|
Changes: Working directory, history log.
|
|||
|
|
@end itemize
|
|||
|
|
|
|||
|
|
This command is meant to safely cancel the effect of
|
|||
|
|
@samp{cvs checkout}. Since @sc{cvs} doesn't lock files, it
|
|||
|
|
isn't strictly necessary to use this command. You can
|
|||
|
|
always simply delete your working directory, if you
|
|||
|
|
like; but you risk losing changes you may have
|
|||
|
|
forgotten, and you leave no trace in the @sc{cvs} history
|
|||
|
|
file (@pxref{history file}) that you've abandoned your
|
|||
|
|
checkout.
|
|||
|
|
|
|||
|
|
Use @samp{cvs release} to avoid these problems. This
|
|||
|
|
command checks that no uncommitted changes are
|
|||
|
|
present; that you are executing it from immediately
|
|||
|
|
above a @sc{cvs} working directory; and that the repository
|
|||
|
|
recorded for your files is the same as the repository
|
|||
|
|
defined in the module database.
|
|||
|
|
|
|||
|
|
If all these conditions are true, @samp{cvs release}
|
|||
|
|
leaves a record of its execution (attesting to your
|
|||
|
|
intentionally abandoning your checkout) in the @sc{cvs}
|
|||
|
|
history log.
|
|||
|
|
|
|||
|
|
@menu
|
|||
|
|
* release options:: release options
|
|||
|
|
* release output:: release options
|
|||
|
|
* release examples:: release examples
|
|||
|
|
@end menu
|
|||
|
|
|
|||
|
|
@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
|
|||
|
|
@node release options
|
|||
|
|
@appendixsubsec release options
|
|||
|
|
|
|||
|
|
The @code{release} command supports one command option:
|
|||
|
|
|
|||
|
|
@table @code
|
|||
|
|
@item -d
|
|||
|
|
Delete your working copy of the file if the release
|
|||
|
|
succeeds. If this flag is not given your files will
|
|||
|
|
remain in your working directory.
|
|||
|
|
|
|||
|
|
@strong{Warning:} The @code{release} command uses
|
|||
|
|
@samp{rm -r @file{module}} to delete your file. This
|
|||
|
|
has the very serious side-effect that any directory
|
|||
|
|
that you have created inside your checked-out sources,
|
|||
|
|
and not added to the repository (using the @code{add}
|
|||
|
|
command; @pxref{add}) will be silently deleted---even
|
|||
|
|
if it is non-empty!
|
|||
|
|
@end table
|
|||
|
|
|
|||
|
|
@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
|
|||
|
|
@node release output
|
|||
|
|
@appendixsubsec release output
|
|||
|
|
|
|||
|
|
Before @code{release} releases your sources it will
|
|||
|
|
print a one-line message for any file that is not
|
|||
|
|
up-to-date.
|
|||
|
|
|
|||
|
|
@strong{Warning:} Any new directories that you have
|
|||
|
|
created, but not added to the @sc{cvs} directory hierarchy
|
|||
|
|
with the @code{add} command (@pxref{add}) will be
|
|||
|
|
silently ignored (and deleted, if @samp{-d} is
|
|||
|
|
specified), even if they contain files.
|
|||
|
|
|
|||
|
|
@table @code
|
|||
|
|
@item U @var{file}
|
|||
|
|
There exists a newer revision of this file in the
|
|||
|
|
repository, and you have not modified your local copy
|
|||
|
|
of the file.
|
|||
|
|
|
|||
|
|
@item A @var{file}
|
|||
|
|
The file has been added to your private copy of the
|
|||
|
|
sources, but has not yet been committed to the
|
|||
|
|
repository. If you delete your copy of the sources
|
|||
|
|
this file will be lost.
|
|||
|
|
|
|||
|
|
@item R @var{file}
|
|||
|
|
The file has been removed from your private copy of the
|
|||
|
|
sources, but has not yet been removed from the
|
|||
|
|
repository, since you have not yet committed the
|
|||
|
|
removal. @xref{commit}.
|
|||
|
|
|
|||
|
|
@item M @var{file}
|
|||
|
|
The file is modified in your working directory. There
|
|||
|
|
might also be a newer revision inside the repository.
|
|||
|
|
|
|||
|
|
@item ? @var{file}
|
|||
|
|
@var{file} is in your working directory, but does not
|
|||
|
|
correspond to anything in the source repository, and is
|
|||
|
|
not in the list of files for @sc{cvs} to ignore (see the
|
|||
|
|
description of the @samp{-I} option, and
|
|||
|
|
@pxref{cvsignore}). If you remove your working
|
|||
|
|
sources, this file will be lost.
|
|||
|
|
|
|||
|
|
Note that no warning message like this is printed for
|
|||
|
|
spurious directories that @sc{cvs} encounters. The
|
|||
|
|
directory, and all its contents, are silently ignored.
|
|||
|
|
|
|||
|
|
@c FIXME -- CVS should be fixed to print "? foo" for
|
|||
|
|
@c such spurious directories
|
|||
|
|
@end table
|
|||
|
|
|
|||
|
|
@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
|
|||
|
|
@node release examples
|
|||
|
|
@appendixsubsec release examples
|
|||
|
|
|
|||
|
|
Release the module, and delete your local working copy
|
|||
|
|
of the files.
|
|||
|
|
|
|||
|
|
@example
|
|||
|
|
$ cd .. # @r{You must stand immediately above the}
|
|||
|
|
# @r{sources when you issue @samp{cvs release}.}
|
|||
|
|
$ cvs release -d tc
|
|||
|
|
You have [0] altered files in this repository.
|
|||
|
|
Are you sure you want to release (and delete) module `tc': y
|
|||
|
|
$
|
|||
|
|
@end example
|
|||
|
|
|
|||
|
|
@node rtag
|
|||
|
|
@appendixsec rtag---Add a tag to the RCS file
|
|||
|
|
@cindex Rtag (subcommand)
|
|||
|
|
|
|||
|
|
@itemize @bullet
|
|||
|
|
@item
|
|||
|
|
rtag [-falnR] [-b] [-d] [-r tag | -Ddate] symbolic_tag modules@dots{}
|
|||
|
|
@item
|
|||
|
|
Requires: repository.
|
|||
|
|
@item
|
|||
|
|
Changes: repository.
|
|||
|
|
@item
|
|||
|
|
Synonym: rfreeze
|
|||
|
|
@end itemize
|
|||
|
|
|
|||
|
|
You can use this command to assign symbolic tags to
|
|||
|
|
particular, explicitly specified source revisions in
|
|||
|
|
the repository. @code{rtag} works directly on the
|
|||
|
|
repository contents (and requires no prior checkout).
|
|||
|
|
Use @code{tag} instead (@pxref{tag}), to base the
|
|||
|
|
selection of revisions on the contents of your
|
|||
|
|
working directory.
|
|||
|
|
|
|||
|
|
If you attempt to use a tag name that already exists,
|
|||
|
|
@sc{cvs} will complain and not overwrite that tag. Use
|
|||
|
|
the @samp{-F} option to force the new tag value.
|
|||
|
|
|
|||
|
|
@menu
|
|||
|
|
* rtag options:: rtag options
|
|||
|
|
@end menu
|
|||
|
|
|
|||
|
|
@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
|
|||
|
|
@node rtag options
|
|||
|
|
@appendixsubsec rtag options
|
|||
|
|
|
|||
|
|
These standard options are supported by @code{rtag}
|
|||
|
|
(@pxref{Common options}, for a complete description of
|
|||
|
|
them):
|
|||
|
|
|
|||
|
|
@table @code
|
|||
|
|
@item -D @var{date}
|
|||
|
|
Tag the most recent revision no later than @var{date}.
|
|||
|
|
|
|||
|
|
@item -f
|
|||
|
|
Only useful with the @samp{-D @var{date}} or @samp{-r @var{tag}}
|
|||
|
|
flags. If no matching revision is found, use the most
|
|||
|
|
recent revision (instead of ignoring the file).
|
|||
|
|
|
|||
|
|
@item -F
|
|||
|
|
Overwrite an existing tag of the same name on a
|
|||
|
|
different revision. This option is new in @sc{cvs}
|
|||
|
|
1.4. The old behavior is matched by @samp{cvs tag -F}.
|
|||
|
|
|
|||
|
|
@item -l
|
|||
|
|
Local; run only in current working directory.
|
|||
|
|
|
|||
|
|
@item -n
|
|||
|
|
Do not run any tag program that was specified with the
|
|||
|
|
@samp{-t} flag inside the @file{modules} file.
|
|||
|
|
(@pxref{modules}).
|
|||
|
|
|
|||
|
|
@item -R
|
|||
|
|
Commit directories recursively. This is on by default.
|
|||
|
|
|
|||
|
|
@item -r @var{tag}
|
|||
|
|
Only tag those files that contain @var{tag}. This can
|
|||
|
|
be used to rename a tag: tag only the files identified
|
|||
|
|
by the old tag, then delete the old tag, leaving the
|
|||
|
|
new tag on exactly the same files as the old tag.
|
|||
|
|
@end table
|
|||
|
|
|
|||
|
|
In addition to the above common options, these options
|
|||
|
|
are available:
|
|||
|
|
|
|||
|
|
@table @code
|
|||
|
|
@item -a
|
|||
|
|
Use the @samp{-a} option to have @code{rtag} look in the
|
|||
|
|
@file{Attic} (@pxref{Removing files}) for removed files
|
|||
|
|
that contain the specified tag. The tag is removed from
|
|||
|
|
these files, which makes it convenient to re-use a
|
|||
|
|
symbolic tag as development continues (and files get
|
|||
|
|
removed from the up-coming distribution).
|
|||
|
|
|
|||
|
|
@item -b
|
|||
|
|
Make the tag a branch tag. @xref{Branches}.
|
|||
|
|
|
|||
|
|
@item -d
|
|||
|
|
Delete the tag instead of creating it.
|
|||
|
|
|
|||
|
|
In general, tags (often the symbolic names of software
|
|||
|
|
distributions) should not be removed, but the @samp{-d}
|
|||
|
|
option is available as a means to remove completely
|
|||
|
|
obsolete symbolic names if necessary (as might be the
|
|||
|
|
case for an Alpha release, or if you mistagged a
|
|||
|
|
module).
|
|||
|
|
@end table
|
|||
|
|
|
|||
|
|
@ignore
|
|||
|
|
@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
|
|||
|
|
@c @node rtag examples
|
|||
|
|
@appendixsubsec rtag examples
|
|||
|
|
|
|||
|
|
@c -- Examples here!
|
|||
|
|
@end ignore
|
|||
|
|
|
|||
|
|
@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
|
|||
|
|
@node status
|
|||
|
|
@appendixsec status---Status info on the revisions
|
|||
|
|
@cindex Status (subcommand)
|
|||
|
|
|
|||
|
|
@itemize @bullet
|
|||
|
|
@item
|
|||
|
|
status [-lR] [-v] [files@dots{}]
|
|||
|
|
@item
|
|||
|
|
Requires: working directory, repository.
|
|||
|
|
@item
|
|||
|
|
Changes: nothing.
|
|||
|
|
@end itemize
|
|||
|
|
|
|||
|
|
Display a brief report on the current status of files
|
|||
|
|
with respect to the source repository, including any
|
|||
|
|
sticky tags, dates, or @samp{-k} options.
|
|||
|
|
|
|||
|
|
You can also use this command to determine the
|
|||
|
|
potential impact of a @samp{cvs update} on your working
|
|||
|
|
source directory---but remember that things might
|
|||
|
|
change in the repository before you run @code{update}.
|
|||
|
|
|
|||
|
|
@menu
|
|||
|
|
* status options:: status options
|
|||
|
|
@end menu
|
|||
|
|
|
|||
|
|
@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
|
|||
|
|
@node status options
|
|||
|
|
@appendixsubsec status options
|
|||
|
|
|
|||
|
|
These standard options are supported by @code{status}
|
|||
|
|
(@pxref{Common options}, for a complete description of
|
|||
|
|
them):
|
|||
|
|
|
|||
|
|
@table @code
|
|||
|
|
@item -l
|
|||
|
|
Local; run only in current working directory.
|
|||
|
|
|
|||
|
|
@item -R
|
|||
|
|
Commit directories recursively. This is on by default.
|
|||
|
|
@end table
|
|||
|
|
|
|||
|
|
There is one additional option:
|
|||
|
|
|
|||
|
|
@table @code
|
|||
|
|
@item -v
|
|||
|
|
Verbose. In addition to the information normally
|
|||
|
|
displayed, print all symbolic tags, together with the
|
|||
|
|
numerical value of the revision or branch they refer
|
|||
|
|
to.
|
|||
|
|
@end table
|
|||
|
|
|
|||
|
|
@ignore
|
|||
|
|
@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
|
|||
|
|
@c @node status examples
|
|||
|
|
@appendixsubsec status examples
|
|||
|
|
|
|||
|
|
@c -- FIXME
|
|||
|
|
@end ignore
|
|||
|
|
|
|||
|
|
@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
|
|||
|
|
@node tag
|
|||
|
|
@appendixsec tag---Add a symbolic tag to checked out version of RCS file
|
|||
|
|
@c -- //////// - unnecessary. Also
|
|||
|
|
@c -- in a lot of other
|
|||
|
|
@c -- places.
|
|||
|
|
@cindex Tag (subcommand)
|
|||
|
|
|
|||
|
|
@itemize @bullet
|
|||
|
|
@item
|
|||
|
|
tag [-lR] [-b] [-d] symbolic_tag [files@dots{}]
|
|||
|
|
@item
|
|||
|
|
Requires: working directory, repository.
|
|||
|
|
@item
|
|||
|
|
Changes: repository.
|
|||
|
|
@item
|
|||
|
|
Synonym: freeze
|
|||
|
|
@end itemize
|
|||
|
|
|
|||
|
|
Use this command to assign symbolic tags to the nearest
|
|||
|
|
repository versions to your working sources. The tags
|
|||
|
|
are applied immediately to the repository, as with
|
|||
|
|
@code{rtag}, but the versions are supplied implicitly by the
|
|||
|
|
@sc{cvs} records of your working files' history rather than
|
|||
|
|
applied explicitly.
|
|||
|
|
|
|||
|
|
One use for tags is to record a snapshot of the
|
|||
|
|
current sources when the software freeze date of a
|
|||
|
|
project arrives. As bugs are fixed after the freeze
|
|||
|
|
date, only those changed sources that are to be part of
|
|||
|
|
the release need be re-tagged.
|
|||
|
|
|
|||
|
|
The symbolic tags are meant to permanently record which
|
|||
|
|
revisions of which files were used in creating a
|
|||
|
|
software distribution. The @code{checkout} and
|
|||
|
|
@code{update} commands allow you to extract an exact
|
|||
|
|
copy of a tagged release at any time in the future,
|
|||
|
|
regardless of whether files have been changed, added,
|
|||
|
|
or removed since the release was tagged.
|
|||
|
|
|
|||
|
|
This command can also be used to delete a symbolic tag,
|
|||
|
|
or to create a branch. See the options section below.
|
|||
|
|
|
|||
|
|
If you attempt to use a tag name that already exists,
|
|||
|
|
@sc{cvs} will complain and not overwrite that tag. Use
|
|||
|
|
the @samp{-F} option to force the new tag value.
|
|||
|
|
|
|||
|
|
|
|||
|
|
@menu
|
|||
|
|
* tag options:: tag options
|
|||
|
|
@end menu
|
|||
|
|
|
|||
|
|
@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
|
|||
|
|
@node tag options
|
|||
|
|
@appendixsubsec tag options
|
|||
|
|
|
|||
|
|
These standard options are supported by @code{tag}
|
|||
|
|
(@pxref{Common options}, for a complete description of
|
|||
|
|
them):
|
|||
|
|
|
|||
|
|
@table @code
|
|||
|
|
@item -F
|
|||
|
|
Overwrite an existing tag of the same name on a
|
|||
|
|
different revision. This option is new in @sc{cvs}
|
|||
|
|
1.4. The old behavior is matched by @samp{cvs tag -F}.
|
|||
|
|
|
|||
|
|
@item -l
|
|||
|
|
Local; run only in current working directory.
|
|||
|
|
|
|||
|
|
@item -R
|
|||
|
|
Commit directories recursively. This is on by default.
|
|||
|
|
@end table
|
|||
|
|
|
|||
|
|
Two special options are available:
|
|||
|
|
|
|||
|
|
@table @code
|
|||
|
|
@item -b
|
|||
|
|
The -b option makes the tag a branch tag
|
|||
|
|
(@pxref{Branches}), allowing concurrent, isolated
|
|||
|
|
development. This is most useful for creating a patch
|
|||
|
|
to a previously released software distribution.
|
|||
|
|
|
|||
|
|
@item -d
|
|||
|
|
Delete a tag.
|
|||
|
|
|
|||
|
|
If you use @samp{cvs tag -d symbolic_tag}, the symbolic
|
|||
|
|
tag you specify is deleted instead of being added.
|
|||
|
|
Warning: Be very certain of your ground before you
|
|||
|
|
delete a tag; doing this permanently discards some
|
|||
|
|
historical information, which may later turn out to
|
|||
|
|
be valuable.
|
|||
|
|
@end table
|
|||
|
|
|
|||
|
|
@ignore
|
|||
|
|
@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
|
|||
|
|
@c @node tag examples
|
|||
|
|
@appendixsubsec tag examples
|
|||
|
|
|
|||
|
|
@c -- FIXME
|
|||
|
|
@end ignore
|
|||
|
|
|
|||
|
|
@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
|
|||
|
|
@node update
|
|||
|
|
@appendixsec update---Bring work tree in sync with repository
|
|||
|
|
@cindex Update (subcommand)
|
|||
|
|
|
|||
|
|
@itemize @bullet
|
|||
|
|
@item
|
|||
|
|
update [-AdflPpR] [-d] [-r tag|-D date] files@dots{}
|
|||
|
|
@item
|
|||
|
|
Requires: repository, working directory.
|
|||
|
|
@item
|
|||
|
|
Changes: working directory.
|
|||
|
|
@end itemize
|
|||
|
|
|
|||
|
|
After you've run checkout to create your private copy
|
|||
|
|
of source from the common repository, other developers
|
|||
|
|
will continue changing the central source. From time
|
|||
|
|
to time, when it is convenient in your development
|
|||
|
|
process, you can use the @code{update} command from
|
|||
|
|
within your working directory to reconcile your work
|
|||
|
|
with any revisions applied to the source repository
|
|||
|
|
since your last checkout or update.
|
|||
|
|
|
|||
|
|
@menu
|
|||
|
|
* update options:: update options
|
|||
|
|
* update output:: update output
|
|||
|
|
* update examples:: update examples
|
|||
|
|
@end menu
|
|||
|
|
|
|||
|
|
@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
|
|||
|
|
@node update options
|
|||
|
|
@appendixsubsec update options
|
|||
|
|
|
|||
|
|
These standard options are available with @code{update}
|
|||
|
|
(@pxref{Common options}, for a complete description of
|
|||
|
|
them):
|
|||
|
|
|
|||
|
|
@table @code
|
|||
|
|
@item -D date
|
|||
|
|
Use the most recent revision no later than @var{date}.
|
|||
|
|
This option is sticky, and implies @samp{-P}.
|
|||
|
|
See @ref{Sticky tags}, for more information on sticky tags/dates.
|
|||
|
|
|
|||
|
|
@item -f
|
|||
|
|
Only useful with the @samp{-D @var{date}} or @samp{-r
|
|||
|
|
@var{tag}} flags. If no matching revision is found,
|
|||
|
|
retrieve the most recent revision (instead of ignoring
|
|||
|
|
the file).
|
|||
|
|
|
|||
|
|
@item -k @var{kflag}
|
|||
|
|
Process @sc{rcs} keywords according to @var{kflag}. See
|
|||
|
|
co(1). This option is sticky; future updates of
|
|||
|
|
this file in this working directory will use the same
|
|||
|
|
@var{kflag}. The @code{status} command can be viewed
|
|||
|
|
to see the sticky options. @xref{status}.
|
|||
|
|
|
|||
|
|
@item -l
|
|||
|
|
Local; run only in current working directory. @xref{Recursive behavior}.
|
|||
|
|
|
|||
|
|
@item -P
|
|||
|
|
Prune empty directories.
|
|||
|
|
|
|||
|
|
@item -p
|
|||
|
|
Pipe files to the standard output.
|
|||
|
|
|
|||
|
|
@item -R
|
|||
|
|
Operate recursively. This is on by default.
|
|||
|
|
@xref{Recursive behavior}.
|
|||
|
|
|
|||
|
|
@item -r tag
|
|||
|
|
Retrieve revision @var{tag}. This option is sticky,
|
|||
|
|
and implies @samp{-P}.
|
|||
|
|
See @ref{Sticky tags}, for more information on sticky tags/dates.
|
|||
|
|
@end table
|
|||
|
|
|
|||
|
|
@need 800
|
|||
|
|
These special options are also available with
|
|||
|
|
@code{update}.
|
|||
|
|
|
|||
|
|
@table @code
|
|||
|
|
@item -A
|
|||
|
|
Reset any sticky tags, dates, or @samp{-k} options.
|
|||
|
|
See @ref{Sticky tags}, for more information on sticky tags/dates.
|
|||
|
|
|
|||
|
|
@item -d
|
|||
|
|
Create any directories that exist in the repository if
|
|||
|
|
they're missing from the working directory. Normally,
|
|||
|
|
@code{update} acts only on directories and files that
|
|||
|
|
were already enrolled in your working directory.
|
|||
|
|
|
|||
|
|
This is useful for updating directories that were
|
|||
|
|
created in the repository since the initial checkout;
|
|||
|
|
but it has an unfortunate side effect. If you
|
|||
|
|
deliberately avoided certain directories in the
|
|||
|
|
repository when you created your working directory
|
|||
|
|
(either through use of a module name or by listing
|
|||
|
|
explicitly the files and directories you wanted on the
|
|||
|
|
command line), then updating with @samp{-d} will create
|
|||
|
|
those directories, which may not be what you want.
|
|||
|
|
|
|||
|
|
@item -I @var{name}
|
|||
|
|
Ignore files whose names match @var{name} (in your
|
|||
|
|
working directory) during the update. You can specify
|
|||
|
|
@samp{-I} more than once on the command line to specify
|
|||
|
|
several files to ignore. Use @samp{-I !} to avoid
|
|||
|
|
ignoring any files at all. @xref{cvsignore}, for other
|
|||
|
|
ways to make @sc{cvs} ignore some files.
|
|||
|
|
|
|||
|
|
@item -W@var{spec}
|
|||
|
|
Specify file names that should be filtered during
|
|||
|
|
update. You can use this option repeatedly.
|
|||
|
|
|
|||
|
|
@var{spec} can be a file name pattern of the same type
|
|||
|
|
that you can specify in the @file{.cvswrappers}
|
|||
|
|
file. @xref{Wrappers}.
|
|||
|
|
|
|||
|
|
@item -j@var{revision}
|
|||
|
|
With two @samp{-j} options, merge changes from the
|
|||
|
|
revision specified with the first @samp{-j} option to
|
|||
|
|
the revision specified with the second @samp{j} option,
|
|||
|
|
into the working directory.
|
|||
|
|
|
|||
|
|
With one @samp{-j} option, merge changes from the
|
|||
|
|
ancestor revision to the revision specified with the
|
|||
|
|
@samp{-j} option, into the working directory. The
|
|||
|
|
ancestor revision is the common ancestor of the
|
|||
|
|
revision which the working directory is based on, and
|
|||
|
|
the revision specified in the @samp{-j} option.
|
|||
|
|
|
|||
|
|
In addition, each -j option can contain an optional
|
|||
|
|
date specification which, when used with branches, can
|
|||
|
|
limit the chosen revision to one within a specific
|
|||
|
|
date. An optional date is specified by adding a colon
|
|||
|
|
(:) to the tag:
|
|||
|
|
@samp{-j@var{Symbolic_Tag}:@var{Date_Specifier}}.
|
|||
|
|
|
|||
|
|
@xref{Merging}.
|
|||
|
|
|
|||
|
|
@end table
|
|||
|
|
|
|||
|
|
@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
|
|||
|
|
@node update output
|
|||
|
|
@appendixsubsec update output
|
|||
|
|
|
|||
|
|
@code{update} keeps you informed of its progress by
|
|||
|
|
printing a line for each file, preceded by one
|
|||
|
|
character indicating the status of the file:
|
|||
|
|
|
|||
|
|
@table @code
|
|||
|
|
@item U @var{file}
|
|||
|
|
The file was brought up to date with respect to the
|
|||
|
|
repository. This is done for any file that exists in
|
|||
|
|
the repository but not in your source, and for files
|
|||
|
|
that you haven't changed but are not the most recent
|
|||
|
|
versions available in the repository.
|
|||
|
|
|
|||
|
|
@item A @var{file}
|
|||
|
|
The file has been added to your private copy of the
|
|||
|
|
sources, and will be added to the source repository
|
|||
|
|
when you run @code{commit} on the file. This is a
|
|||
|
|
reminder to you that the file needs to be committed.
|
|||
|
|
|
|||
|
|
@item R @var{file}
|
|||
|
|
The file has been removed from your private copy of the
|
|||
|
|
sources, and will be removed from the source repository
|
|||
|
|
when you run @code{commit} on the file. This is a
|
|||
|
|
reminder to you that the file needs to be committed.
|
|||
|
|
|
|||
|
|
@item M @var{file}
|
|||
|
|
The file is modified in your working directory.
|
|||
|
|
|
|||
|
|
@samp{M} can indicate one of two states for a file
|
|||
|
|
you're working on: either there were no modifications
|
|||
|
|
to the same file in the repository, so that your file
|
|||
|
|
remains as you last saw it; or there were modifications
|
|||
|
|
in the repository as well as in your copy, but they
|
|||
|
|
were merged successfully, without conflict, in your
|
|||
|
|
working directory.
|
|||
|
|
|
|||
|
|
@sc{cvs} will print some messages if it merges your work,
|
|||
|
|
and a backup copy of your working file (as it looked
|
|||
|
|
before you ran @code{update}) will be made. The exact
|
|||
|
|
name of that file is printed while @code{update} runs.
|
|||
|
|
|
|||
|
|
@item C @var{file}
|
|||
|
|
A conflict was detected while trying to merge your
|
|||
|
|
changes to @var{file} with changes from the source
|
|||
|
|
repository. @var{file} (the copy in your working
|
|||
|
|
directory) is now the output of the rcsmerge(1) command
|
|||
|
|
on the two revisions; an unmodified copy of your file
|
|||
|
|
is also in your working directory, with the name
|
|||
|
|
@file{.#@var{file}.@var{revision}} where @var{revision}
|
|||
|
|
is the @sc{rcs} revision that your modified file started
|
|||
|
|
from. (Note that some systems automatically purge
|
|||
|
|
files that begin with @file{.#} if they have not been
|
|||
|
|
accessed for a few days. If you intend to keep a copy
|
|||
|
|
of your original file, it is a very good idea to rename
|
|||
|
|
it.)
|
|||
|
|
|
|||
|
|
@item ? @var{file}
|
|||
|
|
@var{file} is in your working directory, but does not
|
|||
|
|
correspond to anything in the source repository, and is
|
|||
|
|
not in the list of files for @sc{cvs} to ignore (see the
|
|||
|
|
description of the @samp{-I} option, and
|
|||
|
|
@pxref{cvsignore}).
|
|||
|
|
|
|||
|
|
Note that no warning message like this is printed for
|
|||
|
|
spurious directories that @sc{cvs} encounters. The
|
|||
|
|
directory, and all its contents, are silently ignored.
|
|||
|
|
@end table
|
|||
|
|
|
|||
|
|
@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
|
|||
|
|
@node update examples
|
|||
|
|
@appendixsubsec update examples
|
|||
|
|
|
|||
|
|
The following line will display all files which are not
|
|||
|
|
up-to-date without actually change anything in your
|
|||
|
|
working directory. It can be used to check what has
|
|||
|
|
been going on with the project.
|
|||
|
|
|
|||
|
|
@example
|
|||
|
|
$ cvs -n -q update
|
|||
|
|
@end example
|
|||
|
|
|
|||
|
|
@c ---------------------------------------------------------------------
|
|||
|
|
@node Administrative files
|
|||
|
|
@appendix Reference manual for the Administrative files
|
|||
|
|
@cindex Administrative files (reference)
|
|||
|
|
@cindex Files, reference manual
|
|||
|
|
@cindex Reference manual (files)
|
|||
|
|
@cindex CVSROOT (file)
|
|||
|
|
|
|||
|
|
Inside the repository, in the directory
|
|||
|
|
@file{$CVSROOT/CVSROOT}, there are a number of
|
|||
|
|
supportive files for @sc{cvs}. You can use @sc{cvs} in a limited
|
|||
|
|
fashion without any of them, but if they are set up
|
|||
|
|
properly they can help make life easier.
|
|||
|
|
|
|||
|
|
The most important of these files is the @file{modules}
|
|||
|
|
file, which defines the modules inside the repository.
|
|||
|
|
|
|||
|
|
@menu
|
|||
|
|
* modules:: Defining modules
|
|||
|
|
* Wrappers:: Treat directories as files
|
|||
|
|
* commit files:: The commit support files
|
|||
|
|
* commitinfo:: Pre-commit checking
|
|||
|
|
* editinfo:: Specifying how log messages are created
|
|||
|
|
* loginfo:: Where should log messages be sent?
|
|||
|
|
* rcsinfo:: Templates for the log messages
|
|||
|
|
* cvsignore:: Ignoring files via cvsignore
|
|||
|
|
* history file:: History information
|
|||
|
|
* Setting up:: Setting up the repository
|
|||
|
|
* Variables:: Various variables are expanded
|
|||
|
|
@end menu
|
|||
|
|
|
|||
|
|
@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
|
|||
|
|
@node modules
|
|||
|
|
@appendixsec The modules file
|
|||
|
|
@cindex Modules (admin file)
|
|||
|
|
@cindex Defining modules (reference manual)
|
|||
|
|
|
|||
|
|
The @file{modules} file records your definitions of
|
|||
|
|
names for collections of source code. @sc{cvs} will
|
|||
|
|
use these definitions if you use @sc{cvs} to update the
|
|||
|
|
modules file (use normal commands like @code{add},
|
|||
|
|
@code{commit}, etc).
|
|||
|
|
|
|||
|
|
The @file{modules} file may contain blank lines and
|
|||
|
|
comments (lines beginning with @samp{#}) as well as
|
|||
|
|
module definitions. Long lines can be continued on the
|
|||
|
|
next line by specifying a backslash (@samp{\}) as the
|
|||
|
|
last character on the line.
|
|||
|
|
|
|||
|
|
A module definition is a single line of the
|
|||
|
|
@file{modules} file, in either of two formats. In both
|
|||
|
|
cases, @var{mname} represents the symbolic module name,
|
|||
|
|
and the remainder of the line is its definition.
|
|||
|
|
|
|||
|
|
@table @code
|
|||
|
|
@item @var{mname} -a @var{aliases}@dots{}
|
|||
|
|
This represents the simplest way of defining a module
|
|||
|
|
@var{mname}. The @samp{-a} flags the definition as a
|
|||
|
|
simple alias: @sc{cvs} will treat any use of @var{mname} (as
|
|||
|
|
a command argument) as if the list of names
|
|||
|
|
@var{aliases} had been specified instead.
|
|||
|
|
@var{aliases} may contain either other module names or
|
|||
|
|
paths. When you use paths in aliases, @code{checkout}
|
|||
|
|
creates all intermediate directories in the working
|
|||
|
|
directory, just as if the path had been specified
|
|||
|
|
explicitly in the @sc{cvs} arguments.
|
|||
|
|
|
|||
|
|
@item @var{mname} [ options ] @var{dir} [ @var{files}@dots{} ] [ &@var{module}@dots{} ]
|
|||
|
|
In the simplest case, this form of module definition
|
|||
|
|
reduces to @samp{@var{mname} @var{dir}}. This defines
|
|||
|
|
all the files in directory @var{dir} as module mname.
|
|||
|
|
@var{dir} is a relative path (from @code{$CVSROOT}) to a
|
|||
|
|
directory of source in the source repository. In this
|
|||
|
|
case, on checkout, a single directory called
|
|||
|
|
@var{mname} is created as a working directory; no
|
|||
|
|
intermediate directory levels are used by default, even
|
|||
|
|
if @var{dir} was a path involving several directory
|
|||
|
|
levels.
|
|||
|
|
|
|||
|
|
By explicitly specifying files in the module definition
|
|||
|
|
after @var{dir}, you can select particular files from
|
|||
|
|
directory @var{dir}. The sample definition for
|
|||
|
|
@samp{modules} is an example of a module defined with a
|
|||
|
|
single file from a particular directory. Here is
|
|||
|
|
another example:
|
|||
|
|
|
|||
|
|
@example
|
|||
|
|
m4test unsupported/gnu/m4 foreach.m4 forloop.m4
|
|||
|
|
@end example
|
|||
|
|
|
|||
|
|
@noindent
|
|||
|
|
With this definition, executing @samp{cvs checkout
|
|||
|
|
m4test} will create a single working directory
|
|||
|
|
@file{m4test} containing the two files listed, which
|
|||
|
|
both come from a common directory several levels deep
|
|||
|
|
in the @sc{cvs} source repository.
|
|||
|
|
|
|||
|
|
A module definition can refer to other modules by
|
|||
|
|
including @samp{&@var{module}} in its definition.
|
|||
|
|
@code{checkout} creates a subdirectory for each such
|
|||
|
|
module, in your working directory.
|
|||
|
|
@c -- Nope. "in your working directory" is wrong. What
|
|||
|
|
@c -- is right?
|
|||
|
|
|
|||
|
|
@table @code
|
|||
|
|
@item -d @var{name}
|
|||
|
|
Name the working directory something other than the
|
|||
|
|
module name.
|
|||
|
|
|
|||
|
|
@cindex Export program
|
|||
|
|
@item -e @var{prog}
|
|||
|
|
Specify a program @var{prog} to run whenever files in a
|
|||
|
|
module are exported. @var{prog} runs with a single
|
|||
|
|
argument, the module name.
|
|||
|
|
|
|||
|
|
@cindex Checkin program
|
|||
|
|
@item -i @var{prog}
|
|||
|
|
Specify a program @var{prog} to run whenever files in a
|
|||
|
|
module are committed. @var{prog} runs with a single
|
|||
|
|
argument, the full pathname of the affected directory
|
|||
|
|
in a source repository. The @file{commitinfo},
|
|||
|
|
@file{loginfo}, and @file{editinfo} files provide other
|
|||
|
|
ways to call a program on commit.
|
|||
|
|
|
|||
|
|
@cindex Checkout program
|
|||
|
|
@item -o @var{prog}
|
|||
|
|
Specify a program @var{prog} to run whenever files in a
|
|||
|
|
module are checked out. @var{prog} runs with a single
|
|||
|
|
argument, the module name.
|
|||
|
|
|
|||
|
|
@cindex Status of a module
|
|||
|
|
@cindex Module status
|
|||
|
|
@item -s @var{status}
|
|||
|
|
Assign a status to the module. When the module file is
|
|||
|
|
printed with @samp{cvs checkout -s} the modules are
|
|||
|
|
sorted according to primarily module status, and
|
|||
|
|
secondarily according to the module name. This option
|
|||
|
|
has no other meaning. You can use this option for
|
|||
|
|
several things besides status: for instance, list the
|
|||
|
|
person that is responsible for this module.
|
|||
|
|
|
|||
|
|
@cindex Tag program
|
|||
|
|
@item -t @var{prog}
|
|||
|
|
Specify a program @var{prog} to run whenever files in a
|
|||
|
|
module are tagged with @code{rtag}. @var{prog} runs
|
|||
|
|
with two arguments: the module name and the symbolic
|
|||
|
|
tag specified to @code{rtag}. There is no way to
|
|||
|
|
specify a program to run when @code{tag} is executed.
|
|||
|
|
|
|||
|
|
@cindex Update program
|
|||
|
|
@item -u @var{prog}
|
|||
|
|
Specify a program @var{prog} to run whenever @samp{cvs
|
|||
|
|
update} is executed from the top-level directory of the
|
|||
|
|
checked-out module. @var{prog} runs with a single
|
|||
|
|
argument, the full path to the source repository for
|
|||
|
|
this module.
|
|||
|
|
@end table
|
|||
|
|
@end table
|
|||
|
|
|
|||
|
|
@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
|
|||
|
|
@node Wrappers
|
|||
|
|
@appendixsec The cvswrappers file
|
|||
|
|
@cindex cvswrappers (admin file)
|
|||
|
|
@cindex CVSWRAPPERS, environment variable
|
|||
|
|
@cindex Wrappers
|
|||
|
|
|
|||
|
|
Wrappers allow you to set a hook which transforms files on
|
|||
|
|
their way in and out of @sc{cvs}. Most or all of the
|
|||
|
|
wrappers features do not work with client/server @sc{cvs}.
|
|||
|
|
|
|||
|
|
The file @file{cvswrappers} defines the script that will be
|
|||
|
|
run on a file when its name matches a regular
|
|||
|
|
expresion. There are two scripts that can be run on a
|
|||
|
|
file or directory. One script is executed on the file/directory
|
|||
|
|
before being checked into the repository (this is denoted
|
|||
|
|
with the @code{-t} flag) and the other when the file is
|
|||
|
|
checked out of the repository (this is denoted with the
|
|||
|
|
@code{-f} flag)
|
|||
|
|
|
|||
|
|
The @file{cvswrappers} also has a @samp{-m} option to
|
|||
|
|
specify the merge methodology that should be used when
|
|||
|
|
the file is updated. @code{MERGE} means the usual
|
|||
|
|
@sc{cvs} behavior: try to merge the files (this
|
|||
|
|
generally will not work for binary files). @code{COPY}
|
|||
|
|
means that @code{cvs update} will merely copy one
|
|||
|
|
version over the other, and require the user using
|
|||
|
|
mechanisms outside @sc{cvs}, to insert any necessary
|
|||
|
|
changes.
|
|||
|
|
@c FIXME: which version is copied over which version?
|
|||
|
|
The @samp{-m} wrapper option only affects behavior when
|
|||
|
|
merging is done on update; it does not affect how files
|
|||
|
|
are stored. See @xref{Binary files}, for more on
|
|||
|
|
binary files.
|
|||
|
|
|
|||
|
|
The basic format of the file @file{cvswrappers} is:
|
|||
|
|
|
|||
|
|
@example
|
|||
|
|
wildcard [option value][option value]...
|
|||
|
|
|
|||
|
|
where option is one of
|
|||
|
|
-f from cvs filter value: path tofilter
|
|||
|
|
-t to cvs filter value: path to filter
|
|||
|
|
-m update methodology value: MERGE or COPY
|
|||
|
|
|
|||
|
|
and value is a single-quote delimited value.
|
|||
|
|
@end example
|
|||
|
|
|
|||
|
|
@example
|
|||
|
|
*.nib -f 'unwrap %s' -t 'wrap %s %s' -m 'COPY'
|
|||
|
|
*.c -t 'indent %s %s'
|
|||
|
|
@end example
|
|||
|
|
|
|||
|
|
@noindent
|
|||
|
|
The above example of a @file{cvswrappers} file
|
|||
|
|
states that all files/directories that end with a @code{.nib}
|
|||
|
|
should be filtered with the @file{wrap} program before
|
|||
|
|
checking the file into the repository. The file should
|
|||
|
|
be filtered though the @file{unwrap} program when the
|
|||
|
|
file is checked out of the repository. The
|
|||
|
|
@file{cvswrappers} file also states that a @code{COPY}
|
|||
|
|
methodology should be used when updating the files in
|
|||
|
|
the repository (that is no merging should be performed).
|
|||
|
|
|
|||
|
|
The last example line says that all files that end with
|
|||
|
|
a @code{*.c} should be filtered with @file{indent}
|
|||
|
|
before being checked into the repository. Unlike the previous
|
|||
|
|
example no filtering of the @code{*.c} file is done when
|
|||
|
|
it is checked out of the repository.
|
|||
|
|
@noindent
|
|||
|
|
The @code{-t} filter is called with two arguments,
|
|||
|
|
the first is the name of the file/directory to filter
|
|||
|
|
and the second is the pathname to where the resulting
|
|||
|
|
filtered file should be placed.
|
|||
|
|
|
|||
|
|
@noindent
|
|||
|
|
The @code{-f} filter is called with one argument,
|
|||
|
|
which is the name of the file to filter from. The end
|
|||
|
|
result of this filter will be a file in the users directory
|
|||
|
|
that they can work on as they normally would.
|
|||
|
|
|
|||
|
|
@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
|
|||
|
|
@node commit files
|
|||
|
|
@appendixsec The commit support files
|
|||
|
|
@cindex Commit files
|
|||
|
|
|
|||
|
|
The @samp{-i} flag in the @file{modules} file can be
|
|||
|
|
used to run a certain program whenever files are
|
|||
|
|
committed (@pxref{modules}). The files described in
|
|||
|
|
this section provide other, more flexible, ways to run
|
|||
|
|
programs whenever something is committed.
|
|||
|
|
|
|||
|
|
There are three kind of programs that can be run on
|
|||
|
|
commit. They are specified in files in the repository,
|
|||
|
|
as described below. The following table summarizes the
|
|||
|
|
file names and the purpose of the corresponding
|
|||
|
|
programs.
|
|||
|
|
|
|||
|
|
@table @file
|
|||
|
|
@item commitinfo
|
|||
|
|
The program is responsible for checking that the commit
|
|||
|
|
is allowed. If it exits with a non-zero exit status
|
|||
|
|
the commit will be aborted.
|
|||
|
|
|
|||
|
|
@item editinfo
|
|||
|
|
The specified program is used to edit the log message,
|
|||
|
|
and possibly verify that it contains all required
|
|||
|
|
fields. This is most useful in combination with the
|
|||
|
|
@file{rcsinfo} file, which can hold a log message
|
|||
|
|
template (@pxref{rcsinfo}).
|
|||
|
|
|
|||
|
|
@item loginfo
|
|||
|
|
The specified program is called when the commit is
|
|||
|
|
complete. It receives the log message and some
|
|||
|
|
additional information and can store the log message in
|
|||
|
|
a file, or mail it to appropriate persons, or maybe
|
|||
|
|
post it to a local newsgroup, or@dots{} Your
|
|||
|
|
imagination is the limit!
|
|||
|
|
@end table
|
|||
|
|
|
|||
|
|
@menu
|
|||
|
|
* syntax:: The common syntax
|
|||
|
|
@end menu
|
|||
|
|
|
|||
|
|
@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
|
|||
|
|
@node syntax
|
|||
|
|
@appendixsubsec The common syntax
|
|||
|
|
@cindex Info files (syntax)
|
|||
|
|
@cindex Syntax of info files
|
|||
|
|
@cindex Common syntax of info files
|
|||
|
|
|
|||
|
|
The four files @file{commitinfo}, @file{loginfo},
|
|||
|
|
@file{rcsinfo} and @file{editinfo} all have a common
|
|||
|
|
format. The purpose of the files are described later
|
|||
|
|
on. The common syntax is described here.
|
|||
|
|
|
|||
|
|
Each line contains the following:
|
|||
|
|
@itemize @bullet
|
|||
|
|
@item
|
|||
|
|
A regular expression
|
|||
|
|
|
|||
|
|
@item
|
|||
|
|
A whitespace separator---one or more spaces and/or tabs.
|
|||
|
|
|
|||
|
|
@item
|
|||
|
|
A file name or command-line template.
|
|||
|
|
@end itemize
|
|||
|
|
|
|||
|
|
@noindent
|
|||
|
|
Blank lines are ignored. Lines that start with the
|
|||
|
|
character @samp{#} are treated as comments. Long lines
|
|||
|
|
unfortunately can @emph{not} be broken in two parts in
|
|||
|
|
any way.
|
|||
|
|
|
|||
|
|
The first regular expression that matches the current
|
|||
|
|
directory name in the repository is used. The rest of the line
|
|||
|
|
is used as a file name or command-line as appropriate.
|
|||
|
|
|
|||
|
|
@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
|
|||
|
|
@node commitinfo
|
|||
|
|
@appendixsec Commitinfo
|
|||
|
|
@cindex Commitinfo
|
|||
|
|
@cindex Checking commits
|
|||
|
|
@cindex Precommit checking
|
|||
|
|
|
|||
|
|
The @file{commitinfo} file defines programs to execute
|
|||
|
|
whenever @samp{cvs commit} is about to execute. These
|
|||
|
|
programs are used for pre-commit checking to verify
|
|||
|
|
that the modified, added and removed files are really
|
|||
|
|
ready to be committed. This could be used, for
|
|||
|
|
instance, to verify that the changed files conform to
|
|||
|
|
to your site's standards for coding practice.
|
|||
|
|
|
|||
|
|
As mentioned earlier, each line in the
|
|||
|
|
@file{commitinfo} file consists of a regular expression
|
|||
|
|
and a command-line template. The template can include
|
|||
|
|
a program name and any number of arguments you wish to
|
|||
|
|
supply to it. The full path to the current source
|
|||
|
|
repository is appended to the template, followed by the
|
|||
|
|
file names of any files involved in the commit (added,
|
|||
|
|
removed, and modified files).
|
|||
|
|
|
|||
|
|
The first line with a regular expression matching the
|
|||
|
|
relative path to the module will be used. If the
|
|||
|
|
command returns a non-zero exit status the commit will
|
|||
|
|
be aborted.
|
|||
|
|
|
|||
|
|
@cindex DEFAULT in commitinfo
|
|||
|
|
If the repository name does not match any of the
|
|||
|
|
regular expressions in this file, the @samp{DEFAULT}
|
|||
|
|
line is used, if it is specified.
|
|||
|
|
|
|||
|
|
@cindex ALL in commitinfo
|
|||
|
|
All occurances of the name @samp{ALL} appearing as a
|
|||
|
|
regular expression are used in addition to the first
|
|||
|
|
matching regular expression or the name @samp{DEFAULT}.
|
|||
|
|
|
|||
|
|
Note: when @sc{CVS} is accessing a remote repository,
|
|||
|
|
@file{commitinfo} will be run on the @emph{remote}
|
|||
|
|
(i.e., server) side, not the client side (@pxref{Remote
|
|||
|
|
repositories}).
|
|||
|
|
|
|||
|
|
@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
|
|||
|
|
@node editinfo
|
|||
|
|
@appendixsec Editinfo
|
|||
|
|
@cindex Editinfo
|
|||
|
|
@cindex Editor, specifying per module
|
|||
|
|
@cindex Per-module editor
|
|||
|
|
@cindex Log messages, editing
|
|||
|
|
|
|||
|
|
If you want to make sure that all log messages look the
|
|||
|
|
same way, you can use the @file{editinfo} file to
|
|||
|
|
specify a program that is used to edit the log message.
|
|||
|
|
This program could be a custom-made editor that always
|
|||
|
|
enforces a certain style of the log message, or maybe a
|
|||
|
|
simple shell script that calls an editor, and checks
|
|||
|
|
that the entered message contains the required fields.
|
|||
|
|
|
|||
|
|
If no matching line is found in the @file{editinfo}
|
|||
|
|
file, the editor specified in the environment variable
|
|||
|
|
@code{$CVSEDITOR} is used instead. If that variable is
|
|||
|
|
not set, then the environment variable @code{$EDITOR}
|
|||
|
|
is used instead. If that variable is not
|
|||
|
|
set a precompiled default, normally @code{vi}, will be
|
|||
|
|
used.
|
|||
|
|
|
|||
|
|
The @file{editinfo} file is often most useful together
|
|||
|
|
with the @file{rcsinfo} file, which can be used to
|
|||
|
|
specify a log message template.
|
|||
|
|
|
|||
|
|
Each line in the @file{editinfo} file consists of a
|
|||
|
|
regular expression and a command-line template. The
|
|||
|
|
template must include a program name, and can include
|
|||
|
|
any number of arguments. The full path to the current
|
|||
|
|
log message template file is appended to the template.
|
|||
|
|
|
|||
|
|
One thing that should be noted is that the @samp{ALL}
|
|||
|
|
keyword is not supported. If more than one matching
|
|||
|
|
line is found, the first one is used. This can be
|
|||
|
|
useful for specifying a default edit script in a
|
|||
|
|
module, and then overriding it in a subdirectory.
|
|||
|
|
|
|||
|
|
@cindex DEFAULT in editinfo
|
|||
|
|
If the repository name does not match any of the
|
|||
|
|
regular expressions in this file, the @samp{DEFAULT}
|
|||
|
|
line is used, if it is specified.
|
|||
|
|
|
|||
|
|
If the edit script exits with a non-zero exit status,
|
|||
|
|
the commit is aborted.
|
|||
|
|
|
|||
|
|
Note: when @sc{CVS} is accessing a remote repository,
|
|||
|
|
@file{editinfo} will be run on the @emph{remote}
|
|||
|
|
(i.e., server) side, not the client side (@pxref{Remote
|
|||
|
|
repositories}).
|
|||
|
|
|
|||
|
|
@menu
|
|||
|
|
* editinfo example:: Editinfo example
|
|||
|
|
@end menu
|
|||
|
|
|
|||
|
|
@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
|
|||
|
|
@node editinfo example
|
|||
|
|
@appendixsubsec Editinfo example
|
|||
|
|
|
|||
|
|
The following is a little silly example of a
|
|||
|
|
@file{editinfo} file, together with the corresponding
|
|||
|
|
@file{rcsinfo} file, the log message template and an
|
|||
|
|
editor script. We begin with the log message template.
|
|||
|
|
We want to always record a bug-id number on the first
|
|||
|
|
line of the log message. The rest of log message is
|
|||
|
|
free text. The following template is found in the file
|
|||
|
|
@file{/usr/cvssupport/tc.template}.
|
|||
|
|
|
|||
|
|
@example
|
|||
|
|
BugId:
|
|||
|
|
@end example
|
|||
|
|
|
|||
|
|
The script @file{/usr/cvssupport/bugid.edit} is used to
|
|||
|
|
edit the log message.
|
|||
|
|
|
|||
|
|
@example
|
|||
|
|
#!/bin/sh
|
|||
|
|
#
|
|||
|
|
# bugid.edit filename
|
|||
|
|
#
|
|||
|
|
# Call $EDITOR on FILENAME, and verify that the
|
|||
|
|
# resulting file contains a valid bugid on the first
|
|||
|
|
# line.
|
|||
|
|
if [ "x$EDITOR" = "x" ]; then EDITOR=vi; fi
|
|||
|
|
if [ "x$CVSEDITOR" = "x" ]; then CVSEDITOR=$EDITOR; fi
|
|||
|
|
$CVSEDITOR $1
|
|||
|
|
until head -1|grep '^BugId:[ ]*[0-9][0-9]*$' < $1
|
|||
|
|
do echo -n "No BugId found. Edit again? ([y]/n)"
|
|||
|
|
read ans
|
|||
|
|
case $@{ans@} in
|
|||
|
|
n*) exit 1;;
|
|||
|
|
esac
|
|||
|
|
$CVSEDITOR $1
|
|||
|
|
done
|
|||
|
|
@end example
|
|||
|
|
|
|||
|
|
The @file{editinfo} file contains this line:
|
|||
|
|
|
|||
|
|
@example
|
|||
|
|
^tc /usr/cvssupport/bugid.edit
|
|||
|
|
@end example
|
|||
|
|
|
|||
|
|
The @file{rcsinfo} file contains this line:
|
|||
|
|
|
|||
|
|
@example
|
|||
|
|
^tc /usr/cvssupport/tc.template
|
|||
|
|
@end example
|
|||
|
|
|
|||
|
|
@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
|
|||
|
|
@node loginfo
|
|||
|
|
@appendixsec Loginfo
|
|||
|
|
@cindex Loginfo
|
|||
|
|
@cindex Storing log messages
|
|||
|
|
@cindex Mailing log messages
|
|||
|
|
@cindex Distributing log messages
|
|||
|
|
@cindex Log messages
|
|||
|
|
|
|||
|
|
The @file{loginfo} file is used to control where
|
|||
|
|
@samp{cvs commit} log information is sent. The first
|
|||
|
|
entry on a line is a regular expression which is tested
|
|||
|
|
against the directory that the change is being made to,
|
|||
|
|
relative to the @code{$CVSROOT}. If a match is found, then
|
|||
|
|
the remainder of the line is a filter program that
|
|||
|
|
should expect log information on its standard input.
|
|||
|
|
|
|||
|
|
The filter program may use one and only one % modifier
|
|||
|
|
(a la printf). If @samp{%s} is specified in the filter
|
|||
|
|
program, a brief title is included (enclosed in single
|
|||
|
|
quotes) showing the modified file names.
|
|||
|
|
|
|||
|
|
If the repository name does not match any of the
|
|||
|
|
regular expressions in this file, the @samp{DEFAULT}
|
|||
|
|
line is used, if it is specified.
|
|||
|
|
|
|||
|
|
All occurances of the name @samp{ALL} appearing as a
|
|||
|
|
regular expression are used in addition to the first
|
|||
|
|
matching regular expression or @samp{DEFAULT}.
|
|||
|
|
|
|||
|
|
The first matching regular expression is used.
|
|||
|
|
|
|||
|
|
@xref{commit files}, for a description of the syntax of
|
|||
|
|
the @file{loginfo} file.
|
|||
|
|
|
|||
|
|
Note: when @sc{CVS} is accessing a remote repository,
|
|||
|
|
@file{loginfo} will be run on the @emph{remote}
|
|||
|
|
(i.e., server) side, not the client side (@pxref{Remote
|
|||
|
|
repositories}).
|
|||
|
|
|
|||
|
|
@menu
|
|||
|
|
* loginfo example:: Loginfo example
|
|||
|
|
@end menu
|
|||
|
|
|
|||
|
|
@c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
|
|||
|
|
@node loginfo example
|
|||
|
|
@appendixsubsec Loginfo example
|
|||
|
|
|
|||
|
|
The following @file{loginfo} file, together with the
|
|||
|
|
tiny shell-script below, appends all log messages
|
|||
|
|
to the file @file{$CVSROOT/CVSROOT/commitlog},
|
|||
|
|
and any commits to the administrative files (inside
|
|||
|
|
the @file{CVSROOT} directory) are also logged in
|
|||
|
|
@file{/usr/adm/cvsroot-log}.
|
|||
|
|
@c and mailed to @t{ceder}.
|
|||
|
|
|
|||
|
|
@c FIXME: is it a CVS feature or bug that only the
|
|||
|
|
@c first matching line is used? It is documented
|
|||
|
|
@c above, but is it useful? This example (with the
|
|||
|
|
@c mail to ceder put back in) is awkward to write if
|
|||
|
|
@c only the first matching line is used.
|
|||
|
|
@example
|
|||
|
|
ALL /usr/local/bin/cvs-log $CVSROOT/CVSROOT/commitlog
|
|||
|
|
@c ^CVSROOT Mail -s %s ceder
|
|||
|
|
^CVSROOT /usr/local/bin/cvs-log /usr/adm/cvsroot-log
|
|||
|
|
@end example
|
|||
|
|
|
|||
|
|
The shell-script @file{/usr/local/bin/cvs-log} looks
|
|||
|
|
like this:
|
|||
|
|
|
|||
|
|
@example
|
|||
|
|
#!/bin/sh
|
|||
|
|
(echo "-----------------------------------------------------------------";
|
|||
|
|
echo -n $USER" ";
|
|||
|
|
date;
|
|||
|
|
echo;
|
|||
|
|
sed '1s+'$@{CVSROOT@}'++') >> $1
|
|||
|
|
@end example
|
|||
|
|
|
|||
|
|
@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
|
|||
|
|
@node rcsinfo
|
|||
|
|
@appendixsec Rcsinfo
|
|||
|
|
@cindex Rcsinfo
|
|||
|
|
@cindex Form for log message
|
|||
|
|
@cindex Log message template
|
|||
|
|
@cindex Template for log message
|
|||
|
|
|
|||
|
|
The @file{rcsinfo} file can be used to specify a form to
|
|||
|
|
edit when filling out the commit log. The
|
|||
|
|
@file{rcsinfo} file has a syntax similar to the
|
|||
|
|
@file{editinfo}, @file{commitinfo} and @file{loginfo}
|
|||
|
|
files. @xref{syntax}. Unlike the other files the second
|
|||
|
|
part is @emph{not} a command-line template. Instead,
|
|||
|
|
the part after the regular expression should be a full pathname to
|
|||
|
|
a file containing the log message template.
|
|||
|
|
|
|||
|
|
If the repository name does not match any of the
|
|||
|
|
regular expressions in this file, the @samp{DEFAULT}
|
|||
|
|
line is used, if it is specified.
|
|||
|
|
|
|||
|
|
All occurances of the name @samp{ALL} appearing as a
|
|||
|
|
regular expression are used in addition to the first
|
|||
|
|
matching regular expression or @samp{DEFAULT}.
|
|||
|
|
|
|||
|
|
The log message template will be used as a default log
|
|||
|
|
message. If you specify a log message with @samp{cvs
|
|||
|
|
commit -m @var{message}} or @samp{cvs commit -f
|
|||
|
|
@var{file}} that log message will override the
|
|||
|
|
template.
|
|||
|
|
|
|||
|
|
@xref{editinfo example}, for an example @file{rcsinfo}
|
|||
|
|
file.
|
|||
|
|
|
|||
|
|
When @sc{CVS} is accessing a remote repository,
|
|||
|
|
the contents of @file{rcsinfo} at the time a directory
|
|||
|
|
is first checked out will specify a template which does
|
|||
|
|
not then change. If you edit @file{rcsinfo} or its
|
|||
|
|
templates, you may need to check out a new working
|
|||
|
|
directory.
|
|||
|
|
@c Would be nice to fix CVS so this isn't needed. For
|
|||
|
|
@c example, a mechanism analogous to CVS/Entries, where
|
|||
|
|
@c the client keeps track of what version of the template
|
|||
|
|
@c it has.
|
|||
|
|
|
|||
|
|
@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
|
|||
|
|
@node cvsignore
|
|||
|
|
@appendixsec Ignoring files via cvsignore
|
|||
|
|
@cindex Cvsignore, global
|
|||
|
|
@cindex Global cvsignore
|
|||
|
|
@cindex Ignoring files
|
|||
|
|
@c -- This chapter should maybe be moved to the
|
|||
|
|
@c tutorial part of the manual?
|
|||
|
|
|
|||
|
|
There are certain file names that frequently occur
|
|||
|
|
inside your working copy, but that you don't want to
|
|||
|
|
put under @sc{cvs} control. Examples are all the object
|
|||
|
|
files that you get while you compile your sources.
|
|||
|
|
Normally, when you run @samp{cvs update}, it prints a
|
|||
|
|
line for each file it encounters that it doesn't know
|
|||
|
|
about (@pxref{update output}).
|
|||
|
|
|
|||
|
|
@sc{cvs} has a list of files (or sh(1) file name patterns)
|
|||
|
|
that it should ignore while running @code{update},
|
|||
|
|
@code{import} and @code{release}.
|
|||
|
|
@c -- Are those the only three commands affected?
|
|||
|
|
This list is constructed in the following way.
|
|||
|
|
|
|||
|
|
@itemize @bullet
|
|||
|
|
@item
|
|||
|
|
The list is initialized to include certain file name
|
|||
|
|
patterns: names associated with @sc{cvs}
|
|||
|
|
administration, or with other common source control
|
|||
|
|
systems; common names for patch files, object files,
|
|||
|
|
archive files, and editor backup files; and other names
|
|||
|
|
that are usually artifacts of assorted utilities.
|
|||
|
|
Currently, the default list of ignored file name
|
|||
|
|
patterns is:
|
|||
|
|
|
|||
|
|
@cindex Ignored files
|
|||
|
|
@cindex Automatically ignored files
|
|||
|
|
@example
|
|||
|
|
RCS SCCS CVS CVS.adm
|
|||
|
|
RCSLOG cvslog.*
|
|||
|
|
tags TAGS
|
|||
|
|
.make.state .nse_depinfo
|
|||
|
|
*~ #* .#* ,* _$* *$
|
|||
|
|
*.old *.bak *.BAK *.orig *.rej .del-*
|
|||
|
|
*.a *.olb *.o *.obj *.so *.exe
|
|||
|
|
*.Z *.elc *.ln
|
|||
|
|
core
|
|||
|
|
@end example
|
|||
|
|
|
|||
|
|
@item
|
|||
|
|
The per-repository list in
|
|||
|
|
@file{$CVSROOT/CVSROOT/cvsignore} is appended to
|
|||
|
|
the list, if that file exists.
|
|||
|
|
|
|||
|
|
@item
|
|||
|
|
The per-user list in @file{.cvsignore} in your home
|
|||
|
|
directory is appended to the list, if it exists.
|
|||
|
|
|
|||
|
|
@item
|
|||
|
|
Any entries in the environment variable
|
|||
|
|
@code{$CVSIGNORE} is appended to the list.
|
|||
|
|
|
|||
|
|
@item
|
|||
|
|
Any @samp{-I} options given to @sc{cvs} is appended.
|
|||
|
|
|
|||
|
|
@item
|
|||
|
|
As @sc{cvs} traverses through your directories, the contents
|
|||
|
|
of any @file{.cvsignore} will be appended to the list.
|
|||
|
|
The patterns found in @file{.cvsignore} are only valid
|
|||
|
|
for the directory that contains them, not for
|
|||
|
|
any sub-directories.
|
|||
|
|
@end itemize
|
|||
|
|
|
|||
|
|
In any of the 5 places listed above, a single
|
|||
|
|
exclamation mark (@samp{!}) clears the ignore list.
|
|||
|
|
This can be used if you want to store any file which
|
|||
|
|
normally is ignored by @sc{cvs}.
|
|||
|
|
|
|||
|
|
@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
|
|||
|
|
@node history file
|
|||
|
|
@appendixsec The history file
|
|||
|
|
@cindex History file
|
|||
|
|
@cindex Log information, saving
|
|||
|
|
|
|||
|
|
The file @file{$CVSROOT/CVSROOT/history} is used
|
|||
|
|
to log information for the @code{history} command
|
|||
|
|
(@pxref{history}). This file must be created to turn
|
|||
|
|
on logging. This is done automatically if the
|
|||
|
|
@code{cvs init} command is used to set up the
|
|||
|
|
repository (@pxref{Setting up}).
|
|||
|
|
|
|||
|
|
The file format of the @file{history} file is
|
|||
|
|
documented only in comments in the @sc{cvs} source
|
|||
|
|
code, but generally programs should use the @code{cvs
|
|||
|
|
history} command to access it anyway, in case the
|
|||
|
|
format changes with future releases of @sc{cvs}.
|
|||
|
|
|
|||
|
|
@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
|
|||
|
|
@node Setting up
|
|||
|
|
@appendixsec Setting up the repository
|
|||
|
|
@cindex Repository, setting up
|
|||
|
|
@cindex Creating a repository
|
|||
|
|
@cindex Setting up a repository
|
|||
|
|
|
|||
|
|
To set up a @sc{cvs} repository, choose a directory
|
|||
|
|
with ample disk space available for the revision
|
|||
|
|
history of the source files. It should be accessable
|
|||
|
|
(directly or via a networked file system) from all
|
|||
|
|
machines which want to use @sc{cvs} in server or local
|
|||
|
|
mode; the client machines need not have any access to
|
|||
|
|
it other than via the @sc{cvs} protocol.
|
|||
|
|
|
|||
|
|
To create a repository, run the @code{cvs init}
|
|||
|
|
command. It will set up an empty repository in the
|
|||
|
|
@sc{cvs} root specified in the usual way
|
|||
|
|
(@pxref{Repository}). For example,
|
|||
|
|
|
|||
|
|
@example
|
|||
|
|
cvs -d /usr/local/cvsroot init
|
|||
|
|
@end example
|
|||
|
|
|
|||
|
|
@code{cvs init} is careful to never overwrite any
|
|||
|
|
existing files in the repository, so no harm is done if
|
|||
|
|
you run @code{cvs init} on an already set-up
|
|||
|
|
repository.
|
|||
|
|
|
|||
|
|
@code{cvs init} will enable history logging; if you
|
|||
|
|
don't want that, remove the history file after running
|
|||
|
|
@code{cvs init}. @xref{history file}.
|
|||
|
|
|
|||
|
|
@node Variables
|
|||
|
|
@appendixsec Expansions in administrative files
|
|||
|
|
|
|||
|
|
Sometimes in writing an administrative file, you might
|
|||
|
|
want the file to be able to know various things based
|
|||
|
|
on environment @sc{cvs} is running in. There are
|
|||
|
|
several mechanisms to do that.
|
|||
|
|
|
|||
|
|
To find the home directory of the user running @sc{cvs}
|
|||
|
|
(from the @code{HOME} environment variable), use
|
|||
|
|
@samp{~} followed by @samp{/} or the end of the line.
|
|||
|
|
Likewise for the home directory of @var{user}, use
|
|||
|
|
@samp{~@var{user}}. These variables are expanded on
|
|||
|
|
the server machine, and don't get any resonable
|
|||
|
|
expansion if pserver (@pxref{Password authenticated})
|
|||
|
|
is in used; therefore user variables (see below) may be
|
|||
|
|
a better choice to customize behavior based on the user
|
|||
|
|
running @sc{cvs}.
|
|||
|
|
@c Based on these limitations, should we deprecate ~?
|
|||
|
|
@c What is it good for? Are people using it?
|
|||
|
|
|
|||
|
|
One may want to know about various pieces of
|
|||
|
|
information internal to @sc{cvs}. A @sc{cvs} internal
|
|||
|
|
variable has the syntax @code{$@{@var{variable}@}},
|
|||
|
|
where @var{variable} starts with a letter and consists
|
|||
|
|
of alphanumberic characters and @samp{_}. If the
|
|||
|
|
character following @var{variable} is a
|
|||
|
|
non-alphanumeric character other than @samp{_}, the
|
|||
|
|
@samp{@{} and @samp{@}} can be omitted. The @sc{cvs}
|
|||
|
|
internal variables are:
|
|||
|
|
|
|||
|
|
@table @code
|
|||
|
|
@item CVSROOT
|
|||
|
|
This is the value of the @sc{cvs} root in use.
|
|||
|
|
@xref{Repository}, for a description of the various
|
|||
|
|
ways to specify this.
|
|||
|
|
|
|||
|
|
@item RCSBIN
|
|||
|
|
This is the value @sc{cvs} is using for where to find
|
|||
|
|
@sc{rcs} binaries. @xref{Global options}, for a
|
|||
|
|
description of how to specify this.
|
|||
|
|
|
|||
|
|
@item CVSEDITOR
|
|||
|
|
@itemx VISUAL
|
|||
|
|
@itemx EDITOR
|
|||
|
|
These all expand to the same value, which is the editor
|
|||
|
|
that @sc{cvs} is using. @xref{Global options}, for how
|
|||
|
|
to specify this.
|
|||
|
|
|
|||
|
|
@item USER
|
|||
|
|
Username of the user running @sc{cvs} (on the @sc{cvs}
|
|||
|
|
server machine).
|
|||
|
|
@end table
|
|||
|
|
|
|||
|
|
If you want to pass a value to the administrative files
|
|||
|
|
which the user that is running @sc{cvs} can specify,
|
|||
|
|
use a user variable. To expand a user variable, the
|
|||
|
|
administrative file contains
|
|||
|
|
@code{$@{=@var{variable}@}}. To set a user variable,
|
|||
|
|
specify the global option @samp{-s} to @sc{cvs}, with
|
|||
|
|
argument @code{@var{variable}=@var{value}}. It may be
|
|||
|
|
particularly useful to specify this option via
|
|||
|
|
@file{.cvsrc} (@pxref{~/.cvsrc}).
|
|||
|
|
|
|||
|
|
For example, if you want the administrative file to
|
|||
|
|
refer to a test directory you might create a user
|
|||
|
|
variable @code{TESTDIR}. Then if @sc{cvs} is invoked
|
|||
|
|
as @code{cvs -s TESTDIR=/work/local/tests}, and the
|
|||
|
|
administrative file contains @code{sh
|
|||
|
|
$@{=TESTDIR@}/runtests}, then that string is expanded
|
|||
|
|
to @code{sh /work/local/tests/runtests}.
|
|||
|
|
|
|||
|
|
All other strings containing @samp{$} are reserved;
|
|||
|
|
there is no way to quote a @samp{$} character so that
|
|||
|
|
@samp{$} represents itself.
|
|||
|
|
|
|||
|
|
@c ---------------------------------------------------------------------
|
|||
|
|
@node Environment variables
|
|||
|
|
@appendix All environment variables which affect CVS
|
|||
|
|
@cindex Environment variables
|
|||
|
|
@cindex Reference manual for variables
|
|||
|
|
|
|||
|
|
This is a complete list of all environment variables
|
|||
|
|
that affect @sc{cvs}.
|
|||
|
|
|
|||
|
|
@table @code
|
|||
|
|
@cindex CVSIGNORE
|
|||
|
|
@item $CVSIGNORE
|
|||
|
|
A whitespace-separated list of file name patterns that
|
|||
|
|
@sc{cvs} should ignore. @xref{cvsignore}.
|
|||
|
|
|
|||
|
|
@cindex CVSWRAPPERS
|
|||
|
|
@item $CVSWRAPPERS
|
|||
|
|
A whitespace-separated list of file name patterns that
|
|||
|
|
@sc{cvs} should treat as wrappers. @xref{Wrappers}.
|
|||
|
|
|
|||
|
|
@cindex CVSREAD
|
|||
|
|
@item $CVSREAD
|
|||
|
|
If this is set, @code{checkout} and @code{update} will
|
|||
|
|
try hard to make the files in your working directory
|
|||
|
|
read-only. When this is not set, the default behavior
|
|||
|
|
is to permit modification of your working files.
|
|||
|
|
|
|||
|
|
@cindex CVSROOT
|
|||
|
|
@item $CVSROOT
|
|||
|
|
Should contain the full pathname to the root of the @sc{cvs}
|
|||
|
|
source repository (where the @sc{rcs} history files are
|
|||
|
|
kept). This information must be available to @sc{cvs} for
|
|||
|
|
most commands to execute; if @code{$CVSROOT} is not set,
|
|||
|
|
or if you wish to override it for one invocation, you
|
|||
|
|
can supply it on the command line: @samp{cvs -d cvsroot
|
|||
|
|
cvs_command@dots{}} Once you have checked out a working
|
|||
|
|
directory, @sc{cvs} stores the appropriate root (in
|
|||
|
|
the file @file{CVS/Root}), so normally you only need to
|
|||
|
|
worry about this when initially checking out a working
|
|||
|
|
directory.
|
|||
|
|
|
|||
|
|
@cindex EDITOR
|
|||
|
|
@cindex CVSEDITOR
|
|||
|
|
@item $EDITOR
|
|||
|
|
@itemx $CVSEDITOR
|
|||
|
|
Specifies the program to use for recording log messages
|
|||
|
|
during commit. If not set, the default is
|
|||
|
|
@samp{/usr/ucb/vi}. @code{$CVSEDITOR} overrides
|
|||
|
|
@code{$EDITOR}. @code{$CVSEDITOR} does not exist in
|
|||
|
|
@sc{cvs} 1.3, but the next release will probably
|
|||
|
|
include it.
|
|||
|
|
|
|||
|
|
@cindex PATH
|
|||
|
|
@item $PATH
|
|||
|
|
If @code{$RCSBIN} is not set, and no path is compiled
|
|||
|
|
into @sc{cvs}, it will use @code{$PATH} to try to find all
|
|||
|
|
programs it uses.
|
|||
|
|
|
|||
|
|
@cindex RCSBIN
|
|||
|
|
@item $RCSBIN
|
|||
|
|
Specifies the full pathname of the location of @sc{rcs} programs,
|
|||
|
|
such as co(1) and ci(1). If not set, a compiled-in
|
|||
|
|
value is used, or your @code{$PATH} is searched.
|
|||
|
|
|
|||
|
|
@cindex HOME
|
|||
|
|
@item $HOME
|
|||
|
|
@cindex HOMEPATH
|
|||
|
|
@item $HOMEPATH
|
|||
|
|
Used to locate the directory where the @file{.cvsrc}
|
|||
|
|
file is searched (@code{$HOMEPATH} is used for Windows-NT).
|
|||
|
|
@pxref{~/.cvsrc}
|
|||
|
|
|
|||
|
|
@cindex CVS_RSH
|
|||
|
|
@item $CVS_RSH
|
|||
|
|
Used in client-server mode when accessing a remote
|
|||
|
|
repository using @sc{rsh}. The default value is
|
|||
|
|
@code{rsh}. You can set it to use another program for
|
|||
|
|
accssing the remote server (e.g. for HP-UX 9, you
|
|||
|
|
should set it to @code{remsh} because @code{rsh}
|
|||
|
|
invokes the restricted shell). @pxref{Connecting via
|
|||
|
|
rsh}
|
|||
|
|
|
|||
|
|
@item $CVS_SERVER
|
|||
|
|
Used in client-server mode when accessing a remote
|
|||
|
|
repository using @sc{rsh}. It specifies the name of
|
|||
|
|
the program to start on the server side when accessing
|
|||
|
|
a remote repository using @sc{rsh}. The default value
|
|||
|
|
is @code{cvs}. @pxref{Connecting via rsh}
|
|||
|
|
|
|||
|
|
@item $CVS_PASSFILE
|
|||
|
|
Used in client-server mode when accessing the @code{cvs
|
|||
|
|
login server}. Default value is @file{$HOME/.cvspass}.
|
|||
|
|
@pxref{Password authentication client}
|
|||
|
|
|
|||
|
|
@item $CVS_PASSWORD
|
|||
|
|
Used in client-server mode when accessing the @code{cvs
|
|||
|
|
login server}.
|
|||
|
|
@pxref{Password authentication client}
|
|||
|
|
|
|||
|
|
@item $CVS_CLIENT_PORT
|
|||
|
|
Used in client-server mode when accessing the server
|
|||
|
|
via Kerberos.
|
|||
|
|
@pxref{Kerberos authenticated}
|
|||
|
|
|
|||
|
|
@cindex CVS_RCMD_PORT
|
|||
|
|
@item $CVS_RCMD_PORT
|
|||
|
|
Used in client-server mode. If set, specifies the port
|
|||
|
|
number to be used when accessing the @sc{rcmd} demon on
|
|||
|
|
the server side. (Currently not used for Unix clients).
|
|||
|
|
|
|||
|
|
@cindex CVS_CLIENT_LOG
|
|||
|
|
@item $CVS_CLIENT_LOG
|
|||
|
|
Used for debugging only in client-server
|
|||
|
|
mode. If set, everything send to the server is logged
|
|||
|
|
into @file{@code{$CVS_CLIENT_LOG}.in} and everything
|
|||
|
|
send from the server is logged into
|
|||
|
|
@file{@code{$CVS_CLIENT_LOG}.out}.
|
|||
|
|
|
|||
|
|
@cindex CVS_SERVER_SLEEP
|
|||
|
|
@item $CVS_SERVER_SLEEP
|
|||
|
|
Used only for debugging the server side in
|
|||
|
|
client-server mode. If set, delays the start of the
|
|||
|
|
server child process the the specified amount of
|
|||
|
|
seconds so that you can attach to it with a debugger.
|
|||
|
|
|
|||
|
|
@cindex CVS_IGNORE_REMOTE_ROOT
|
|||
|
|
@item $CVS_IGNORE_REMOTE_ROOT
|
|||
|
|
(What is the purpose of this variable?)
|
|||
|
|
|
|||
|
|
@cindex COMSPEC
|
|||
|
|
@item $COMSPEC
|
|||
|
|
Used under OS/2 only. It specifies the name of the
|
|||
|
|
command interpreter and defaults to @sc{cmd.exe}.
|
|||
|
|
|
|||
|
|
|
|||
|
|
@end table
|
|||
|
|
|
|||
|
|
@sc{cvs} is a front-end to @sc{rcs}. The following environment
|
|||
|
|
variables affect @sc{rcs}. Note that if you are using
|
|||
|
|
the client/server @sc{cvs}, these variables need to be
|
|||
|
|
set on the server side (which may or not may be
|
|||
|
|
possible depending on how you are connecting). There
|
|||
|
|
is probably not any need to set any of them, however.
|
|||
|
|
|
|||
|
|
@table @code
|
|||
|
|
@cindex LOGNAME
|
|||
|
|
@item $LOGNAME
|
|||
|
|
@cindex USER
|
|||
|
|
@itemx $USER
|
|||
|
|
If set, they affect who @sc{rcs} thinks you are. If you
|
|||
|
|
have trouble checking in files it might be because your
|
|||
|
|
login name differs from the setting of e.g.
|
|||
|
|
@code{$LOGNAME}.
|
|||
|
|
|
|||
|
|
@cindex RCSINIT
|
|||
|
|
@item $RCSINIT
|
|||
|
|
Options prepended to the argument list, separated by
|
|||
|
|
spaces. A backslash escapes spaces within an option.
|
|||
|
|
The @code{$RCSINIT} options are prepended to the
|
|||
|
|
argument lists of most @sc{rcs} commands.
|
|||
|
|
|
|||
|
|
@cindex TMPDIR
|
|||
|
|
@item $TMPDIR
|
|||
|
|
@cindex TMP
|
|||
|
|
@itemx $TMP
|
|||
|
|
@cindex TEMP
|
|||
|
|
@itemx $TEMP
|
|||
|
|
Name of the temporary directory. The environment
|
|||
|
|
variables are inspected in the order they appear above
|
|||
|
|
and the first value found is taken; if none of them are
|
|||
|
|
set, a host-dependent default is used, typically
|
|||
|
|
@file{/tmp}.
|
|||
|
|
@end table
|
|||
|
|
|
|||
|
|
@c ---------------------------------------------------------------------
|
|||
|
|
@node Troubleshooting
|
|||
|
|
@appendix Troubleshooting
|
|||
|
|
|
|||
|
|
@menu
|
|||
|
|
* Magic branch numbers:: Magic branch numbers
|
|||
|
|
@end menu
|
|||
|
|
|
|||
|
|
@ignore
|
|||
|
|
@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
|
|||
|
|
@c @node Bad administrative files
|
|||
|
|
@appendixsec Bad administrative files
|
|||
|
|
|
|||
|
|
@c -- Give hints on how to fix them
|
|||
|
|
@end ignore
|
|||
|
|
|
|||
|
|
@c - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
|
|||
|
|
@node Magic branch numbers
|
|||
|
|
@appendixsec Magic branch numbers
|
|||
|
|
|
|||
|
|
Externally, branch numbers consist of an odd number of
|
|||
|
|
dot-separated decimal integers. @xref{Revision
|
|||
|
|
numbers}. That is not the whole truth, however. For
|
|||
|
|
efficiency reasons @sc{cvs} sometimes inserts an extra 0
|
|||
|
|
in the second rightmost position (1.2.3 becomes
|
|||
|
|
1.2.0.3, 8.9.10.11.12 becomes 8.9.10.11.0.12 and so
|
|||
|
|
on).
|
|||
|
|
|
|||
|
|
@sc{cvs} does a pretty good job at hiding these so
|
|||
|
|
called magic branches, but in at least four places the
|
|||
|
|
hiding is incomplete.
|
|||
|
|
|
|||
|
|
@itemize @bullet
|
|||
|
|
@item
|
|||
|
|
The magic branch can appear in the output from
|
|||
|
|
@code{cvs status} in vanilla @sc{cvs} 1.3. This is
|
|||
|
|
fixed in @sc{cvs} 1.3-s2.
|
|||
|
|
|
|||
|
|
@item
|
|||
|
|
The magic branch number appears in the output from
|
|||
|
|
@code{cvs log}. This is much harder to fix, since
|
|||
|
|
@code{cvs log} runs @code{rlog} (which is part of the
|
|||
|
|
@sc{rcs} distribution), and modifying @code{rlog} to
|
|||
|
|
know about magic branches would probably break someone's
|
|||
|
|
habits (if they use branch 0 for their own purposes).
|
|||
|
|
|
|||
|
|
@item
|
|||
|
|
You cannot specify a symbolic branch name to @code{cvs log}.
|
|||
|
|
|
|||
|
|
@item
|
|||
|
|
You cannot specify a symbolic branch name to @code{cvs
|
|||
|
|
admin}.
|
|||
|
|
|
|||
|
|
@end itemize
|
|||
|
|
|
|||
|
|
You can use the @code{admin} command to reassign a
|
|||
|
|
symbolic name to a branch the way @sc{rcs} expects it
|
|||
|
|
to be. If @code{R4patches} is assigned to the branch
|
|||
|
|
1.4.2 (magic branch number 1.4.0.2) in file
|
|||
|
|
@file{numbers.c} you can do this:
|
|||
|
|
|
|||
|
|
@example
|
|||
|
|
$ cvs admin -NR4patches:1.4.2 numbers.c
|
|||
|
|
@end example
|
|||
|
|
|
|||
|
|
It only works if at least one revision is already
|
|||
|
|
committed on the branch. Be very careful so that you
|
|||
|
|
do not assign the tag to the wrong number. (There is
|
|||
|
|
no way to see how the tag was assigned yesterday).
|
|||
|
|
|
|||
|
|
@c ---------------------------------------------------------------------
|
|||
|
|
@node Copying
|
|||
|
|
@appendix GNU GENERAL PUBLIC LICENSE
|
|||
|
|
@c @include gpl.texinfo
|
|||
|
|
|
|||
|
|
@c ---------------------------------------------------------------------
|
|||
|
|
@node Index
|
|||
|
|
@unnumbered Index
|
|||
|
|
@cindex Index
|
|||
|
|
|
|||
|
|
@printindex cp
|
|||
|
|
|
|||
|
|
@summarycontents
|
|||
|
|
|
|||
|
|
@contents
|
|||
|
|
|
|||
|
|
@bye
|
|||
|
|
|
|||
|
|
Local Variables:
|
|||
|
|
fill-column: 55
|
|||
|
|
End:
|