.\" 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.,  59 Temple Place - Suite 330, Boston,
.\" MA 02111-1307, USA.
.\"
.\" $Id: cvs-inject.1,v 1.18 2003/03/13 18:05:58 srivasta Exp $
.\"
.TH CVS\-INJECT 1 "May 13 1999" "Debian" "Debian GNU/Linux manual"
.SH NAME
cvs\-inject \- inject a debian source package into a CVS repository
.SH SYNOPSIS
.B cvs\-inject
.I [options]
.B <package>.dsc
.SH DESCRIPTION
This manual page explains the Debian
.B "cvs\-inject"
utility, which is used to inject or import Debian source packages into
a  
.I CVS
repository. It handles Debian\-only packages (which do not have diff
files) as well as normal packages from
.I upstream
sources converted to Debian use.
.PP
The upstream sources are imported to the vendor branch and tagged
.I upstream_version_<upstream version>
with all dots translated to under scores. The debianized sources, if
different, are put on the main branch, and tagged 
.I debian_version_<upstream version>-<debian revision>
with all dots translated to under scores.
.PP
The sole argument is a debian source .dsc file, which is parsed to get
the package name and version.
.B cvs\-inject
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.
.PP
This utility can be used to generate a unified CVS source tree,
for example, 
with
.PP
 find /var/spool/mirror/debian/hamm/hamm/source \\
               -type f -name \\*.dsc | while read i; 
     do    
        j=$(dirname $i | sed -e s:source/::           \\
               -e s:/var/spool/mirror/debian/:: )
        cvs-inject -x$j $i
     done
.PP 
Which happily gobbled up the sources and created a CVS repository
on my machine until the partition filled up.
.SH CAVEATS
Please note that the current behaviour of 
.B cvs\-inject 
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
If you wish to modify this behaviour, there are ways to do this (you
should see 
.B CVS
documentation). 
.TP 
.B o)
The per-repository list in 
.I `$CVSROOT/CVSROOT/cvsignore'
is appended to the list, if that file exists.
.TP
.B o)
The per-user list in
.I `.cvsignore'
in your home directory is appended to the list, if it exists.
.TP 
.B o)
Any entries in the environment variable
.I $CVSIGNORE 
is appended to the list.
.PP
In any of the places listed above, a single exclamation mark
.B (`!') 
clears the ignore list.  This can be used if you want to store any
file which normally is ignored by CVS. Also, any 
.I .cvsignore 
file found in the source directory is also honoured. If you wish to
specify your own list on the command line, you may use the
environment variable
.B CVSDEB_IMPORTSUBSTMODE
(for example, 
.I CVSDEB_IMPORTSUBSTMODE="! -I blah -ko -d "
).
.PP
.SH OPTIONS
.TP 20
.B \-h
Print out a usage message.
.TP
.B \-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
.B CVSDEB_USE_CHANGELOG
.TP
.BR \-M<module>
The name of the CVS module. This argument overrides the
settings in the environment variable
.B CVSDEB_MODULE.
There is no corresponding config file variable.
.TP
.BR \-F
There are two things 
.B CVS
may choke on
.I symbolic links
and
.I CVS
directories in the source tree. Also, there are times when one may
not want to honour the upstream 
.I .cvsignore 
files. Without this option, the 
.B cvs-inject
program shall exit with an error message. This option causes 
.B cvs-inject 
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
.B CVSDEB_FORCECLEAN,
which in turn overrides the setting in the configuration file,
.B conf_forceclean.
.TP
.B \-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.
.TP
.B \-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.
.TP
.BR \-x<prefix>
The name of the default CVS prefix (that is, this is appended to 
.B CVSROOT
when looking for the repository).  This argument overrides the
settings in the environment variable
.B CVSDEB_PREFIX,
which in turn overrides the setting in the configuration file,
.B conf_prefix.
.TP
.B \-R<root\ directory>
Root of the original sources archive. 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
.B CVSDEB_ROOTDIR,
and the configuration file variable
.B 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
.B CVSROOT,
since cvs shall refuse to export packages there, and the script shall
fail. 
.TP
.B \-W<work directory>
The full path name for the cvs-buildpackage working directory.
Setting this variable overrides the settings for the root directory.
This argument also overrides the settings in the environment variable
.B CVSDEB_WORKDIR,
and in the configuration file variable
.B conf_workdir..
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, and needs to be the full (absolute)
path name.  This should probably not be a sub dir of
.B CVSROOT,
since cvs shall refuse to export packages there, and the script shall
fail. The default is 
.I /usr/local/src/Packages/
.TP
.B \-d<number>
Turn on debugging output. This lists the version numbers, the
cvs-buildpackage 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 \-ctp
Include
.IB package _
at the start of the CVS tag.  This overrides the
.B CVSDEB_PACKAGEINTAG
environment variable and the
.B conf_forcetag
configuration file option.  The default is not to include the prefix.
.TP
.B \-n
The no exec (or dry-run) option, causing
.B cvs\-inject
to print out all actions that would be taken without actually
executing them..
.TP
.B \-v
Make the utility more verbose.
.TP
.B CVSDEB_IMPORTSUBSTMODE
You are also allowed to specify an environment variable,
.B CVSDEB_IMPORTSUBSTMODE,
that overrides the default substitution option of -ko.  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).
.SH FILES
Apart from the runtime options,
.B cvs\-inject
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 cvs-buildpackage 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-upgrade (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.