Ubuntu Manpage: cvs-upgrade - upgrade a debian source package kept in a CVS repository

NAME

       cvs-upgrade - upgrade a debian source package kept in a CVS repository

SYNOPSIS

       cvs-upgrade [options] <package name> <upstream version> [<debian revision>]

DESCRIPTION

This manual page explains the Debian cvs-upgrade utility, which is used to upgrade Debian source packages
in a CVS repository. It expect a properly conditioned new upstream sources in the cvs-buildpackage work
directory

The upstream sources are imported to the vendor branch and tagged upstream_version_<upstream version>
with all dots translated to underscores. At this point the cvs-upgrade utility pauses automatic actions,
since manual intervention is required to resolve any conflicts that may have occurred. It reminds the
user about checking out the sources, resolving conflicts, and tagging the debianized sources, using
debian_version_<upstream version>-<debian revision> with all dots translated to underscores.

Please note that this command does not actually change the working directory, or any checked out copies.
If you do not have a working directory, you may simply do the following manually:
cvs co -jupstream_version_<OLD-VERS> -jupstream_version_<NEW VERS> <PKG>

If you already have a checked out working directory, please do:
cvs update -d -jupstream_version_<OLD-VERS> -jupstream_version__<NEW VERS>

cvs-upgrade expects the package name, upstream version, and, if relevant, the Debian revision on the
command line. It also expects to find a properly conditioned new upstream source archive, in .orig.tar.gz
format, in the cvs-buildpackage working directory. Please note that the cvs-buildpackage work directory
referred to here is the scratch directory where this program works, not the directory that the human uses
to work in.

cvs-upgrade reads the same config file /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.

Combined with the companion utilities cvs-buildpackage and cvs-inject, this provides an infrastructure to
facilitate the use of CVS by Debian maintainers. This allows one to keep separate CVS branches of a
package for stable, unstable, and possibly experimental distributions, along with the other benefits of a
version control system.

CAVEATS

       Please note that the current behaviour of 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 .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:
              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

       If you wish to modify this behaviour, there are ways to do this (you should see CVS documentation).

       o)     The  per-repository  list  in  `$CVSROOT/CVSROOT/cvsignore'  is appended to the list, if that file
              exists.

       o)     The per-user list in `.cvsignore' in your home directory is appended to the list, if it exists.

       o)     Any entries in the environment variable $CVSIGNORE is appended to the list.

       In any of the places listed above, a single exclamation mark (`!')  clears the ignore list.  This can  be
       used  if  you want to store any file which normally is ignored by CVS. Also, any .cvsignore file found in
       the source directory is also honoured.

OPTIONS

-h Print out a usage message.

-m If present, this option directs this program to include the latest debian changelog,
if any, into the commit message. This overrides the environment variable
CVSDEB_USE_CHANGELOG

-M<module> The name of the CVS module. This argument overrides the settings in the environment
variable CVSDEB_MODULE. There is no corresponding config file variable.

-F There are two things CVS may choke on symbolic links and CVS directories in the
source tree. Also, there are times when one may not want to honour the upstream
.cvsignore files. Without this option, the cvs-upgrade program shall exit with an
error message. This option causes cvs-upgrade to ask whether you want to delete the
offending files. If you answer y, it removes them and continues; else it shall exit
with an error message. This argument overrides the settings in the environment
variable CVSDEB_FORCECLEAN, which in turn overrides the setting in the configuration
file, conf_forceclean.

-T<tag> The CVS tag to use for exporting sources, rather than constructing one from the
version. This assumes you know what you are doing.

-U<tag> The CVS tag to use for the upstream tag, rather than constructing one from the
upstream version. This assumes you know what you are doing.

-x<prefix> The name of the default CVS prefix. This argument overrides the settings in the
environment variable CVSDEB_PREFIX, which in turn overrides the setting in the
configuration file, conf_prefix.

-R<root directory> Root of the original sources archive. We expect to find the
<package name>_<version>.orig.tar.gz file under <root directory>/package name>/
unless the cvs-buildpackage work directory has been set, or we want to export the
original sources from the vendor branch of the CVS tree. If the cvs-buildpackage 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 overrides the settings in the
environment variable CVSDEB_ROOTDIR, and the configuration file variable
conf_rootdir. Please note that the cvs-buildpackage work directory referred to here
is the scratch directory where this program works, not the directory that the human
uses to work in. This should probably not be a sub dir of CVSROOT, since cvs shall
refuse to export packages there, and the script shall fail.

-W<work directory> The working directory, into which the sources will be exported out of CVS and which
should contain the original <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 upstream_version_<version> (without the Debian
revision). Setting this variable overrides the settings for the root directory. This
argument also overrides the settings in the environment variable CVSDEB_WORKDIR, and
in the configuration file variable conf_workdir. This should probably not be a sub
dir of CVSROOT, since cvs shall refuse to export packages there, and the script shall
fail.

-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 overrides the
DEBUG variable in the configuration file.

-ctp Include package_ at the start of the CVS tag. This overrides the CVSDEB_PACKAGEINTAG
environment variable and the conf_forcetag configuration file option. The default is
not to include the prefix.

-n The no exec (or dry-run) option, causing cvs-upgrade to print out all actions that
would be taken without actually executing them.

-v Make the utility more verbose.

CVSDEB_IMPORTSUBSTMODE
You are also allowed to specify an environment variable, CVSDEB_IMPORTSUBSTMODE, that
overrides the default substitution option of -ko -d. This is useful when you want to
import a package that has a bunch of binary files in the source tree (like emacs or
rscheme).

FILES

       Apart   from   the   runtime  options,  cvs-upgrade  also  looks  for  site-wide  defaults  in  the  file
       /etc/cvsdeb.conf.  After that, it looks for and reads ~/.cvsdeb.conf  The  default  configuration  allows
       there  to  be  a site-wide override for the root or the cvs-buildpackage working directories on the site,
       but the cvsdeb.conf files are actually Bourne shell snippets, and  any  legal  shell  directives  may  be
       included  in there.  Note: Caution is urged with this file, since you can totally change the way that the
       script behaves by suitable editing this file.

AUTHOR

       This manual page was written Manoj Srivastava <srivasta@debian.org>, for the Debian GNU/Linux system.