Provided by: cvs-buildpackage_5.23_all bug

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.

SEE ALSO

       cvs-buildpackage(1), cvs-inject(1), cvsdeb.conf(5), cvs(1).

AUTHOR

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