.\" Hey, Emacs! This is an -*- nroff -*- source file.
.\" Copyright (c) 1997 Manoj Srivastava <srivasta@debian.org>
.\"
.\" This is free documentation; you can redistribute it and/or
.\" modify it under the terms of the GNU General Public License as
.\" published by the Free Software Foundation; either version 2 of
.\" the License, or (at your option) any later version.
.\"
.\" The GNU General Public License's references to "object code"
.\" and "executables" are to be interpreted as the output of any
.\" document formatting or typesetting system, including
.\" intermediate and printed output.
.\"
.\" This manual is distributed in the hope that it will be useful,
.\" but WITHOUT ANY WARRANTY; without even the implied warranty of
.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
.\" GNU General Public License for more details.
.\"
.\" You should have received a copy of the GNU General Public
.\" License along with this manual; if not, write to the Free
.\" Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139,
.\" USA.
.\"
.\" $Id: cvs-upgrade.1,v 1.3 1998/03/02 08:25:30 srivasta Exp $
.\"
.TH CVS\-UPGRADE 1 "Feb 20 1998" "Debian" "Debian GNU/Linux manual"
.SH NAME
cvs\-upgrade \- upgrade a debian source package kept in a CVS repository
.SH SYNOPSIS
.B cvs\-upgrade
.I [options]
.B <package Name>
.B <Upstream Version>
.B [<debian revision>]
.SH DESCRIPTION
This manual page explains the Debian
.B "cvs\-upgrade"
utility, which is used to upgrade Debian source packages in
a  
.I CVS
repository. It expect a properly conditioned new upstream sources 
in the 
.I work directory
.PP
The upstream sources are imported to the vendor branch and tagged
.I upstream_versions_<upstream version>
with all dots translated to under scores. At this point the 
.B cvs\-upgrade
utility pauses automatic actions, since manual intervention is
required to resolve any conflicts that may have occured.
It reminds the user about checking out the sources, resolving
conflicts, and tagging the debianized sources, with 
.I debian_version_<upstream version>-<debian revision>
with all dots translated to under scores.
.PP
It expects the package name, upstream version, and , if relevant, the
Debian reviosion on the cmmand line. I also expects to find a properly
conditioned new upstream sources file in the .orig.tar.gz format in
the 
.I working directory.
.PP
.B cvs\-upgrade
reads the same config file
.I /etc/cvsdeb.conf
as the the other cvs-* utilities do.
People may use of the dry run option to inspect the steps this
utility takes. 
.PP
Combined with the companion utilities
.B cvs\-buildpackage 
and  
.B cvs\-upgrade,
this provides an infrastructure to facilitate the use of
.B CVS
by Debian maintainers. This allows one to keep separate CVS branches
of a package for 
.I stable, 
.I unstable, 
and possibly 
.I experimental
distributions, along with the other benefits of a version control
system.
.SH CAVEATS
Please not that the current behaviour of 
.B cvs\-upgrade
is to ignore files that match the default list of file name patterns
to be ignored (this is built into cvs); and that any 
.B .cvsignore 
files in the upstream sources shall be honoured. This should be fine
as long as upstream sources do not include files that match cvs ignore
patterns and yet should be in the sources. The current list of ignored
file name patterns is:
.RS 
.B RCS SCCS CVS CVS.adm RCSLOG cvslog.* tags TAGS .make.state
.B .nse_depinfo *~ #* .#* ,* _$* *$ *.old *.bak *.BAK *.orig *.rej .del-*
.B *.a *.olb *.o *.obj *.so *.exe *.Z *.elc *.ln core
.RE
.PP
.SH OPTIONS
.TP 20
.B \-h
Print out a usage message.
.TP
.BR \-M<module>
The name of the CVS module. This argument over rides the
settings in the environment variable
.B CVSDEB_MODULE.
There is no corresponding config file variable.
.TP
.BR \-x<prefix>
The name of the default CVS prefix.  This argument over rides the
settings in the environment variable
.B CVSDEB_PREFIX,
which in turn over rides the setting in the configuration file,
.B conf_prefix.
.TP
.B \-R<root\ directory>
Root of the original sources archive. We expect to find the
.I <package\ name>_<version>.orig.tar.gz
file under
.I <root\ directory>/package\ name>/
unless the work directory has been set, or we want to export the
original sources from the vendor branch of the 
.I CVS
tree. If the work directory is set
anywhere, (command line, configuration file, environment variable), the root
directory value is ignored, since we only need the root directory to
set defaults for the work directory. This argument over rides the
settings in the environment variable
.B CVSDEB_ROOTDIR,
and the configuration file variable
.B conf_rootdir.
.TP
.B \-W<work directory>
The working directory, into which the sources will be exported out of
CVS and which should contain the original
.I <package\ name>_<version>.orig.tar.gz
Please note that it is not essential to have the original sources, as
this script will check out the vendor branch version tagged as
.B upstream_version_<version>
(without the Debian revision)
Setting this variable makes the settings for the root directory. This
argument over rides the settings in the environment variable
.B CVSDEB_WORKDIR,
and in the configuration file variable
.B conf_workdir.
.TP
.B \-d<number>
Turn on debugging output. This lists the version numbers, the work and
root directories, as well as the CVS tag used to export the
sources. This over\-rides the 
.I DEBUG
variable in the configuration file.
.TP
.B \-n
The no exec (or dry-run) option, causing
.B cvs\-upgrade
to print out all actions that would be taken without actually
executing them..
.TP
.B \-v
Make the utility more verbose.
.TP
.SH FILES
Apart from the runtime options,
.B cvs\-upgrade
also looks for site\-wide defaults in the file
.I /etc/cvsdeb.conf.
After that, it looks for and reads
.I \~/.cvsdeb.conf
The default configuration allows there to be a site wide override for
the root or the working directories on the site, but the
.I cvsdeb.conf
files are actually Bourne shell snippets, and any legal shell directives
may be included in there.
.B Note:
Caution is urged with this file, since you can totally change the way
that the script behaves by suitable editing this file.
.SH "SEE ALSO"
.BR cvs-buildpackage (1),
.BR cvs-inject (1),
.BR cvsdeb.conf (5),
.BR cvs (1).
.SH AUTHOR
This manual page was written Manoj Srivastava <srivasta@debian.org>,
for the Debian GNU/Linux system.