.TH REPREPRO 1 "1 November, 2006" "reprepro" REPREPRO
.SH NAME
reprepro \- produce, manage and sync a local repository of debian packages
.SH SYNOPSIS
.B reprepro \-\-help

.B reprepro
[
\fIoptions\fP
]
\fIcommand\fP
[ 
\fIper\-command\-arguments\fP 
]
.SH DESCRIPTION
reprepro is a tool to manage a repository of Debian packages
(.deb, .udeb, .dsc, ...). 
It stores files either being injected manually or 
downloaded from some other repository (partially) mirrored 
into a pool/ hierarchy. 
Managed packages and checksums of files are stored in a libdb4.3
database (or libdb4.4 or libdb3, depending what reprepro was compiled with), 
so no database server is needed. 
Checking signatures of mirrored repositories and creating
signatures of the generated Package indices is supported.

.B WARNING: Some functions are still quite experimental and not very heavily tested. Be careful.

Former working title of this program was mirrorer.
.SH "GLOBAL OPTIONS"
Options can be specified before the command. Each affects a different
subset of commands and is ignored by other commands.
.TP
.B \-h \-\-help
Displays a short list of options and commands with description.
.TP
.B \-v, \-V, \-\-verbose
Be more verbose. Can be applied multiple times. One upcase 
.B \-V 
counts as five lowercase 
.B \-v.
.TP
.B \-f, \-\-force
This option is ignored, as it no longer exists.
.TP
.B \-b, \-\-basedir \fIbasedir\fP
Sets the base\-dir of the repository to manage, i.e. where the
.B pool/
subdirectory resides.
If none is supplied and the
.B REPREPRO_BASE_DIR
environment variable is not set either, the current directory
will be used.
.TP
.B \-\-confdir \fIconfdir\fP
Sets the directory where the configuration is searched in.

If none is given, \fIbasedir\fP\fB/conf\fP will be used.
.TP
.B \-\-distdir \fIdistdir\fP
Sets the directory to generate index files relatively to. (i.e. things like
Packages.gz, Sources.gz and Release.gpg)

If none is given, \fIbasedir\fP\fB/dists\fP is used.

.B Note: 
apt has 
.B dists
hard-coded in it, so this is mostly only useful for testing or when your webserver
pretends another directory structure than your physical layout.

.B Warning:
Beware when changing this forth and back between two values not ending
in the same directory.
Reprepro only looks if files it wants are there. If nothing of the content
changed and there is a file it will not touch it, assuming it is the one it
wrote last time, assuming any different \fB\-\-distdir\fP ended in the same
directory.
So either clean a directory before setting \fB\-\-distdir\fP to it or
do an \fBexport\fP with the new one first to have a consistent state.
.TP
.B \-\-dbdir \fIdbdir\fP
Sets the directory where reprepro keeps its databases.

If none is given, \fIbasedir\fP\fB/db\fP is used.

.B Note:
This is permanent data, no cache. One has almost to regenerate the whole
repository when this is lost.
.TP
.B \-\-listdir \fIlistdir\fP
Sets the directory where downloads it downloads indices to when importing
from other repositories. This is temporary data and can be safely deleted
when not in an update run.

If none is given, \fIbasedir\fP\fB/lists\fP is used.
.TP
.B \-\-overridedir \fIoverridedir\fP
Sets the directory where specified override\-files will be searched in if
they do not start with a slash.
If none is given, \fIbasedir\fP\fB/override\fP is used.
.TP
.B \-\-methoddir \fImethoddir\fP
Look in \fImethoddir\fP instead of
.B /usr/lib/apt/methods
for methods to call when importing from other repositories.
.TP
.B \-C, \-\-component \fIcomponent\fP
Specify a component to force into, to remove from or to list only.
.TP
.B \-A, \-\-architecture \fIarchitecture\fP
Specify an architecture to only include into, remove from or
list.

When including this does not lead to packages in the wrong architecture
but will restrict effect to this architecture. This allows e.g. different
versions of an
.B Architecture: all
\-package in different architectures of the same distribution.
.TP
.B \-T, \-\-type \fRdsc|deb|udeb
Specify which type of files to include, remove or list.
.TP
.B \-S, \-\-section \fIsection\fP
Overrides the section of inclusions. (Also override possible override files)
.TP
.B \-P, \-\-priority \fIpriority\fP
Overrides the priority of inclusions. (Also override possible override files)
.TP 
.BR \-\-export= ( never | changed | normal | force )
This option specify whether and how the high level actions
(e.g. install, update, pull, delete)
should export the index files of the distributions they work with.
.TP
.BR \-\-export=normal " (default)"
In this mode every distribution the action handled without error
will be exported.
.br
\fINote\fP that only missing files and files whose intended content changed
between before and after the action will be written.
To get a guaranteed current export, use the \fBexport\fP action.
.TP
.BR \-\-export=changed
Like \fBnormal\fP, but do not look for missing files in distributions where
nothing changed.
.TP
.BR \-\-export=force
Like \fBnormal\fP, but exporting also happens for distributions where
some error occurred.
.TP
.BR \-\-export=never
No index files are exported. You will have to call \fBexport\fP later.
.br
\fINote\fP that you most likely additionally need the \fB\-\-keepunreferenced\fP
option, if you do want some of the files pointed to by the untouched index
files to vanish.
.TP
.B \-\-ignore=\fIwhat\fP
Ignore errors of type \fIwhat\fP. See the section \fBERROR IGNORING\fP
for possible values.
.TP
.B \-\-nolistsdownload
When running \fBupdate\fP or \fBcheckupdate\fP do not download any Release
or index files (and also do not check them). This is hardly useful except
when you just run one of those command for the same distributions.
.TP 
.B \-\-keepunreferencedfiles
Do not delete files that are no longer used because the package they
are from is deleted/replaced with a newer version from the last distribution
it was in.
.TP 
.B \-\-keepunneededlists
Do not try to delete files from \fBlists/\fP before updating, that seem to
belong to one of the updated distributions but will not be needed. 
Those file may happen to exist when you removed 
some Update: rule or changed Components/Architectures/... .
This is mostly only useful if you want to temporarily disable some update
rule and want to avoid downloading their index files again when you read
it later.
.TP 
.B \-\-keepdirectories
Do not try to rmdir parent directories after files or directories
have been removed from them.
(Do this if your directories have special permissions you want keep,
do not want to be pestered with warnings about errors to remove them,
or have a buggy rmdir call deleting non-empty directories.)
.TP 
.B \-\-ask\-passphrase
Ask for passphrases when signing things and one is needed. This is a quick
and dirty implementation using the obsolete \fBgetpass(3)\fP function
with the description gpgme is supplying. So the prompt will look quite
funny and support for passphrases with more than 8 characters depend on your libc.
I suggest using gpg\-agent or something like that instead.
.TP 
.B \-\-noskipold
When updating do not skip targets where no new index files and no files
marked as already processed are available.

If you changed a script to preprocess downloaded index files or
changed a Listfilter, you most likely want to call reprepro with \-\-noskipold.
.SH COMMANDS
.TP
.BR export " [ " \fIcodenames\fP " ]"
Generate all index files for the specified distributions. (For all if none
is specified). This will normally be done automatically and more
fine\-tuned when including or removing packages, so seldom needed; but is nevertheless 
a good way to see if
a new 
.B distributions
config\-file does the expected things.
.TP
.BR createsymlinks " [ " \-\-delete " ] [ " \fIcodenames\fP " ]"
Creates \fIsuite\fP symbolic links in the \fBdists/\fP-directory pointing
to the corresponding \fIcodename\fP.

It will not create links, when multiple of the given codenames
would be linked from the same suite name, or if the link
already exists (though when \fB\-\-delete\fP is given it
will delete already existing symlinks)
.TP
.B list \fIcodename\fP \fIpackagename\fP
List all packages (source and binary, except when
.B \-T 
or
.B \-A
is given) with the given name in all components (except when
.B \-C
is given) and architectures (except when
.B \-A
is given) of the specified distribution.
.TP
.B listfilter \fIcodename\fP \fIcondition\fP
as list, but does not list a single package, but all packages
matching the given condition.

.B reprepro \-b . \-T deb listfilter test2 'Source (==blub) | ( !Source , Package (==blub) )'
will e.g. find all .deb Packages with Source blub. (Except those also specifying a version
number with its Source, as binary and source version differ).
.TP
.B remove \fIcodename\fP \fIpackage name\fP
same as list, but remove instead of list.
.TP
.BR update " [ " \fIcodenames\fP " ]"
Sync the specified distributions (all if none given) as
specified in the config with their upstreams. See the
description of
.B conf/updates
below.
.TP
.BR iteratedupdate " [ " \fIcodenames\fP " ] (EXPERIMENTAL!)"
This is an experimental variant of update, that processes
the distributions and targets within them one by one,
resulting in much lower memory consumption for an update
of multiple distributions.
.TP
.BR checkupdate " [ " \fIcodenames\fP " ]"
Same like
.BR update ,
but will show what it will change instead of actually changing it.
.TP
.BR predelete " [ " \fIcodenames\fP " ]"
This will determine which packages a \fBupdate\fP would delete or
replace and remove those packages.
This can be useful for reducing space needed while upgrading, but
there will be some time where packages are vanished from the
lists so clients will mark them as obsolete.
Plus if you cannot
download a updated package in the (hopefully) following update
run, you will end up with no package at all instead of an old one.
This will also blow up pindex files if you are using the tiffany
example or something similar.
So be careful when using this option or better get some more space so
that update works.
.TP
.BR pull " [ " \fIcodenames\fP " ]"
pull in newer packages into the specified distributions (all if none given)
from other distributions in the same repository.
See the description of
.B conf/pulls
below.
.TP
.BR checkpull " [ " \fIcodenames\fP " ]"
Same like
.BR pull ,
but will show what it will change instead of actually changing it.
.TP
.B includedeb \fIcodename\fP \fI.deb-filename\fP
Include the given binary Debian package (.deb) in the specified
distribution, applying override information and guessing all 
values not given and guessable.
.TP
.B includeudeb \fIcodename\fP \fI.deb-filename\fP
Same like \fBincludedeb\fP, but for .udeb files.
.TP
.B includedsc \fIcodename\fP \fI.dsc-filename\fP
Include the given Debian source package (.dsc, including other files
like .orig.tar.gz, .tar.gz and/or .diff.gz) in the specified
distribution, applying override information and guessing all values 
not given and guessable.

Note that as .dsc files do not contain section or priority, but the
Sources.gz file does, you have to either specify a DscOverride or
given them via
.B \-S
and
.B \-P
.TP
.B include  \fIcodename\fP \fI.changes-filename\fP
Include in the specified distribution all packages found and suitable
in the \fI.changes\fP file, applying override information guessing all 
values not given and guessable.
.TP
.BR check " [ " \fIcodenames\fP " ]"
Check if all packages in the specified distributions have all files
needed properly registered.
.TP
.BR checkpool " [ " fast " ]"
Check if all files believed to be in the pool are actually still there and
have the known md5sum. When 
.B fast
is specified md5sum is not checked.
.TP
.B rereference
Forget which files are needed and recollect this information.
.TP
.B dumpreferences
Print out which files are marked to be needed by whom.
.TP
.B dumpunreferenced
Print a list of all filed believed to be in the pool, that are
not known to be needed.
.TP
.B deleteunreferenced
Remove all known files (and forget them) in the pool not marked to be
needed by anything.
.TP
.BR reoverride " [ " \fIcodenames\fP " ]"
Reapply the override files to the given distributions (Or only parts
thereof given by \fB\-Af\fP,\fB\-C\fP or \fB\-T\fP).

Note: only the control information is changed. Changing a section
to a value, that would cause an other component to be guessed, will
not cause any warning.
.TP
.BR dumptracks " [ " \fIcodenames\fP " ]"
Print out all information about tracked source packages in the
given distributions.
.TP
.BR retrack " [ " \fIcodenames\fP " ]"
Recreate a tracking database for the specified distributions.
As this only takes information from the Indices into account,
this will loose all information about older packages or
changes files.
.TP
.BR cleartracks " [ " \fIcodenames\fP " ]"
Removes all source package tracking information for the
given distributions.
.TP
.B removetrack " " \fIcodename\fP " " \fIsourcename\fP " " \fIversion\fP
Remove the trackingdata of the given version of a given sourcepackage
from a given distribution. This also removes the references for all
used files.
.TP
.B copy \fIdestination-codename\fP \fIsource-codename\fP \fIpackages...\fP
Copy the given packages from one distribution to another. No overrides
are read, nothing is changed.
.TP
.B clearvanished
Remove all package databases that no longer appear in \fBconf/distributions\fP.
If \fB\-\-delete\fP is specified, it will not stop if there are still
packages left.
Even without \fB\-\-delete\fP it will unreference
files still marked as needed by this target.
(Use \fB\-\-keepunreferenced\fP to not delete them if that was the last
reference.)

Do not forget to remove all exported package indices manually.
.SS internal commands
These are hopefully never needed, but allow manual intervention.
.B WARNING:
Is is quite easy to get into an inconsistent and/or unfixable state.
.TP
.BR _detect " [ " \fIfilekeys\fP " ]"
Look for the files, which \fIfilekey\fP
is given as argument or as a line of the input 
(when run without arguments), and calculate
their md5sum and add them to the list of known files.
(Warning: this is a low level operation, no input validation
or normalization is done.)
.TP
.BR _forget " [ " \fIfilekeys\fP " ]"
Like
.B _detect
but remove the given \fIfilekey\fP from the list of known
files.
(Warning: this is a low level operation, no input validation
or normalization is done.)
.TP
.B _listmd5sums
Print a list of all known files and their md5sums.
.TP
.B _addmd5sums
Add information of known files (without any check done)
in the strict format of _listmd5sums output (i.e. don't dare to
use a single space anywhere more than needed). 
.TP
.BI _dumpcontents " identifier"
Printout all the stored information of the specified
part of the repository. (Or in other words, the content
the corresponding Packages or Sources file would get)
.TP
.BI "_addreference " filekey " " identifier
Manually mark \fIfilekey\fP to be needed by \fIidentifier\fP
.TP
.BI "_removereferences " identifier
Remove all references what is needed by
.I identifier.
.TP
.BI __extractcontrol .deb-filename
Look what reprepro believes to be the content of the
.B control
file of the specified .deb-file.
.SH "CONFIG FILES"
.B reprepo 
uses three config files, which are searched in
the directory specified with 
.B \-\-confdir
or in the
.B conf/
subdirectory of the \fIbasedir\fP.

If an file
.B options
exists, it is parsed line by line. 
Each line can be the long
name of an command line option (without the \-\-) 
plus an argument, where possible.
Those are handled as if they were command line options given before
(and thus lower priority than) any other command line option.
(and also lower priority than any environment variable).

To allow command line options to override options file options,
most boolean options also have a corresponding form starting with \fB\-\-no\fP.

(The only exception is when the path to look for config files
changes, the options file will only opened once and of course
before any options within the options file are parsed.)

The file
.B distributions
is always needed and describes what distributions
to manage, while
.B updates
is only needed when syncing with external repositories.

The last both are in the format control files in Debian are in,
i.e. paragraphs separated by blank lines consisting of
fields. Each field consists of an fieldname, followed
by a colon, possible whitespace and the data. A field
ends with a newline not followed by a space or tab.
.SS conf/distributions
.TP
.B Codename
This required field is the unique identifier of a distribution
and used as directory name within 
.B dists/
It is also copied into the Release files.
.TP
.B Suite
This optional field is simply copied into the
Release files. In Debian it contains names like
stable, testing or unstable. To create symlinks
from the Suite to the Codename, use the
\fBcreatesymlinks\fP command of reprepro.
.TP
.B Version
This optional field is simply copied into the
Release files.
.TP
.B Origin
This optional field is simply copied into the
Release files.
.TP
.B Label
This optional field is simply copied into the
Release files.
.TP
.B NotAutomatic
This optional field is simply copied into the
Release files. 
(The value is handled as arbitrary string,
though anything but \fByes\fP does make much
sense right now.)
.TP
.B Description
This optional field is simply copied into the
Release files.
.TP
.B Architectures
This required field lists the binary architectures within
this distribution and if it contains
.B source
(i.e. if there is an item
.B source
in this line this Distribution has source. All other items
specify things to be put after "binary\-" to form directory names
and be checked against "Architecture:" fields.)

This will also be copied into the Release files. (With exception
of the
.B source
item, which will not occur in the topmost Release file whether
it is present here or not)
.TP
.B Components
This required field lists the component of a
distribution. See 
.B GUESSING
for rules which component packages are included into
by default. This will also be copied into the Release files.
.TP
.B UDebComponents
Components with a debian\-installer subhierarchy containing .udebs.
(E.g. simply "main")
.TP
.B Update
When this field is present, it describes which update rules are used
for this distribution. There also can be a magic rule minus ("\-"),
see below.
.TP
.B Pull
When this field is present, it describes which pull rules are used
for this distribution.
Pull rules are like Update rules,
but get their stuff from other distributions and not from external sources.
See the description for \fBconf/pulls\fP.
.TP
.B SignWith
When this field is present, a Release.gpg file will be generated.
If the value is "yes" and "default", the default key
is used.
Otherwise the value will be given to libgpgme to determine to key to 
use.
(That should be roughly the one \fBgpg \-\-list\-secret\-keys\fP \fIvalue\fP would output).
This key should either have no passphrase, you need to specify
\fB\-\-ask\-passphrase\fP or use gpg\-agent.
.TP
.B DebOverride
When this field is present, it describes the override file used
when including .deb files.
.TP
.B UDebOverride
When this field is present, it describes the override file used
when including .deb files.
.TP
.B DscOverride
When this field is present, it describes the override file used
when including .dsc files.
.TP
.B DebIndices\fR, \fBUDebIndices\fR, \fBDscIndices
Choose what kind of Index files to export. The first
part describes what the Index file shall be called.
The second argument determines the name of a Release
file to generate or not to generate if missing.
Then at least one of "\fB.\fP", "\fB.gz\fP"  or "\fB.bz2\fP"
specifying whether to generate uncompressed output, gzipped
output, bzip2ed output or any combination.
(bzip2 is only available when compiled with bzip2 support,
so it might not be available when you compiled it on your
own).
If an argument not starting with dot follows,
it will be executed after all index files are generated.
(See the examples for what argument this gets).
The default is:
.br
DebIndices Packages Release . .gz
.br
UDebIndices Packages . .gz
.br
DscIndices Sources Release .gz
.TP
.B Contents
Enable the creation of Contents files listing all the files
within the binary packages of a distribution.
(Which is quite slow, you have been warned).

The first argument is the rate at which to extract the files
from packages.
If it is 1, every file will be processed.
If it is 2, at least half of the uncached files and at most half
of all files are read to extract their filelist.
If it is 3, at least a third of yet uncached files and at most a
third of all files is read.
And so on...

After that a space separated list of options can be given.
If there is a \fBudebs\fP keyword, \fB.udeb\fPs are also listed
(in a file called \fBuContents\-\fP\fIarchitecture\fP.)
If there is a \fBnodebs\fP keyword, \fB.deb\fPs are not listed.
(Only usefull together with \fBudebs\fP)
If there is at least one of the keywords \fB.\fP, \fB.gz\fP and/or \fB.bz2\fP,
the Contents files are written uncompressed, gzipped and/or bzip2ed instead
of only gzipped.
.TP
.B ContentsArchitectures
Limit generation of Contents files to the architectures given.
If this field is not there or empty, all architectures are processed.
.TP
.B ContentsComponents
Limit what components are processed for the Contents files to
the components given.
If this field is not there or empty, all components are processed.
.TP
.B ContentsUComponents
Limit what components are processed for the uContents files to
the components given.
If this field is not there or empty, all components are processed.
(Note unless you specify \fBudebs\fP in the \fBContents:\fP line,
no udeb Components are processed at all.)
.TP
.B Uploaders
Specified a file (relative to confdir if not starting with a slash)
to specify who is allowed to upload packages. With this there are no
limits, and this file can be ignored via \fB\-\-ignore=uploaders\fP.
See the section \fBUPLOADERS FILES\fP below.
.TP
.B Tracking
Enable the (experimental) tracking of source packages.
The argument list needs to contain exactly one of the following:
.br
.B keep
Keeps all files of a given source package, until that
is deleted explicitly via \fBremovetrack\fP. This is
currently the only possibility to keep older packages
around when all indices contain newer files.
.br
.B all
Keep all files belonging to a given source package until
the last file of it is no longer used within that
distribution.
.br
.B minimal
Remove files no longer included in the tracked distribution.
(Remove changes and includebyhand files once no file is
in any part of the distribution).
.br
And any number of the following (or none):
.br
.B includechanges
Add the .changes file to the tracked files of an source
package. Thus it is also put into the pool.
.br
.B includebyhand
Not yet implemented.
.br
.B ambargoalls
Not yet implemented.
.B keepsources
Even when using minimal mode, do not remove source files
until no file is needed any more.
.B needsources
Not yet implemented.
.SS conf/updates
.TP
.B Name
The name of this update\-upstream as it can be used in the 
.B Update
field in conf/distributions.
.TP
.B Method
An URI as one could also give it apt, e.g.
.I http://ftp.debian.de/debian
which is simply given to the corresponding
.B apt\-get
method. (So either
.B apt\-get has to be installed, or you have to point with
.B \-\-methoddir
to a place where such methods are found.
.TP
.B Fallback
(Still experimental:) A fallback URI, where all files are
tried that failed the first one. They are given to the
same method as the previous URI (e.g. both http://), and
the fallback-server must have everything at the same place.
No recalculation is done, but single files are just retried from
this location.
.TP
.B Config
This can contain any number of lines, each in the format
.B apt\-get \-\-option
would expect. (Multiple lines \(hy as always \(hy marked with
leading spaces).
.P
For example: Config: Acquire::Http::Proxy=http://proxy.yours.org:8080
.TP
.B Suite
The suite to update from. If this is not present, the codename
of the distribution using this one is used. Also "*/whatever"
is replaced by "<codename>/whatever"
.TP
.B Components
The components to update. Each item can be either the name
of a component or a pair of a upstream component and a local
component separated with ">". (e.g. "main>all contrib>all non\-free>notall")
Items with a local part are ignored. If no items are there
all from the updated distribution are taken. (Use some non existing
like "none", if you want none).
.TP
.B Architectures
The architectures to update. If omitted all from the distribution
to update from. (As with components, you can use ">" to download
from one Architecture and add into an other one. (This only determine
in which Package list they land, it neither overwrites the Architecture
line in its description, nor the one in the filename determined from this
one. In other words, it is no really useful without additional things)
.TP
.B UDebComponents
Like
.B Components
but for the udebs.
.TP
.B VerifyRelease
Download the
.B Release.gpg
file and check if it is a signature of the
.B Releasefile 
with the key given here. (In the Format as
"gpg \-\-with\-colons \-\-list\-key" prints it, i.e. the last
16 hex digits of the fingerprint) Multiple keys can be specified
by separating them with a "|" sign. Then finding a signature
from one of the will suffice.
.TP
.B IgnoreRelease
If this is present, no
.B Release
file will be downloaded and thus the md5sums of the other
index files will not be checked.
.TP
.B FilterFormula
This can be a formula to specify which packages to accept from
this source. The format is misusing the parser intended for
Dependency lines. To get only architecture all packages use
"architecture (== all)", to get only at least important
packages use "priority (==required) | priority (==important)".
.TP
.B FilterList
This takes at least two arguments: The first one is the default action
when something is not found, the then a list of
filenames (relative to
.B \-\-confdir\fR,
if not starting with a slash), 
in the format of dpkg \-\-get\-selections and only packages listed in
there as 
.B install
will be installed. Things listed as
.B deinstall
or 
.B purge
or nonexistent will be treated like not being known.
A package being
.B hold
will not be upgraded but also not downgraded or removed.
To abort the whole upgrade/pull if a package is available, use
.B error\fR.
.TP
.B ListHook
If this is given, it is executed for all downloaded index files
with the downloaded list as first and a filename that will
be used instead of this. (e.g. "ListHook: /bin/cp" works
but does nothing.)
.SS conf/pulls
This file contains the rules for pulling packages from one
distribution to another.
While this can also be done with update rules using the file
or copy method and using the exported indices of that other
distribution, this way is faster.
It also ensures the current files are used and no copies
are made.
(This also leads to the limitation that pulling from one
component to another is not possible.)

Each rule consists out of the following fields:
.TP
.B Name
The name of this pull rule as it can be used in the 
.B Pull
field in conf/distributions.
.TP
.B From
The codename of the distribution to pull packages from.
.TP
.B Components
The components of the distribution to get from.
Unknown items are ignored to ease rule reuse.
If there are no items, all components from distribution are taken.
(Use some non existing like "none", if you want none).
.TP
.B Architectures
The architectures to update.
If omitted all from the distribution to pull from.
.TP
.B UDebComponents
Like
.B Components
but for the udebs.
.TP
.B FilterFormula
.TP
.B FilterList
The same as with update rules.
.SH "OVERRIDE FILES"
Override files are yet only used when things are manually added,
not when imported while updating from an external source.
The format should resemble the extended ftp\-archive format,
to be specific it is:

.B \fIpackagename\fP \fIfield name\fP \fInew value\fP

For example:
.br
.B kernel\-image\-2.4.31\-yourorga Section protected/base
.br
.B kernel\-image\-2.4.31\-yourorga Priority standard
.br
.B kernel\-image\-2.4.31\-yourorga Maintainer That's me <me@localhost>
.br
.B reprepro Priority required

All fields of a given package will be replaced by the new value specified
in the override file.
While the field name is compared case-insensitive, it is copied in
exactly the form in the override file there.
(Thus I suggest to keep to the exact case it is normally found in 
index files in case some other tool confuses them.)
More than copied is the Section header (unless \fB\-S\fP is supplied),
which is also used to guess the component (unless \fB\-C\fP is there).
There is no protection against changing headers like \fBPackage\fP, 
\fBFilename\fP, \fBSize\fP or \fBMD5sum\fP, though changing these functional
fields may give the most curious results.
(Most likely reprepro may error out in future invocations).
.SH "UPLOADERS FILES"
These files specified by the \fBUploaders\fP header in the distribution
definition as explained above describe what key a \fB.changes\fP file
as to be signed with to be included in that distribution.
.P
Empty lines and lines starting with a hash are ignored, every other line
has to be of one of this three forms:
.br
.B accept * by unsigned
.br
which allows everything without a valid signature in,
.br
.B accept * by any key
.br
which allows everything with any valid signature in or
.br
.B accept * by key \fIkey-id\fP
.br
which allows everything signed by this \fIkey-id\fP (to be specified
without any spaces) in.
.P
(Other statements
will follow once somebody tells me what restrictions are usefull).
.SH "ERROR IGNORING"
With \fB\-\-ignore\fP on the command line or an \fIignore\fP
line in the options file, the following type of errors can be
ignored:
.TP
.B brokenold \fR(hopefully never seen)
If there are errors parsing an installed version of package, do not 
error out, but assume it is older than anything else, has not files
or no source name.
.TP
.B brokensignatures
If a .changes or .dsc file contains at least one invalid signature
and no valid signature (not even expired or from an expired or revoked key),
reprepro assumes the file got corrupted and refuses to use it unless this
ignore directive is given.
.TP
.B brokenversioncmp \fR(hopefully never seen)
If comparing an old and a new version fails, assume the new one is newer.
.TP
.B doublefield \fR(better comment the second one)
Ignore doubled fields in the config files,
instead of refusing to run then.
In general the second one should be ignored then, but
perhaps sometimes the first one.
So I hope you know what you do.
.TP
.B emptyfilenamepart \fR(insecure)
Allow strings to be empty that are used to construct filenames.
(like versions, architectures, ...)
.TP
.B extension
Allow to \fBincludedeb\fP files that do not end with \fB.deb\fP,
to \fBincludedsc\fP files not ending in \fB.dsc\fP and to
\fBinclude\fP files not ending in \fB.changes\fP.
.TP
.B forbiddenchar \fR(insecure)
Do not insist on Debian policy for package and source names
and versions.
Thus allowing all 7-bit characters but slashes (as they would
break the file storage) and things syntactically active
(spaces, underscores in filenames in .changes files, opening
parentheses in source names of binary packages).
To allow some 8-bit chars additionally, use \fB8bit\fP additionally.
.TP
.B 8bit \fR(more insecure)
Allow 8-bit characters not looking like overlong UTF-8 sequences
in filenames and things used as parts of filenames.
Though it hopefully rejects overlong UTF-8 sequences, there might
be other characters your filesystem confuses with special characters,
thus creating filenames possibly equivalent to 
\fB/mirror/pool/main/../../../etc/shadow\fP 
(Which should be save, as you do not run reprepro as root, do you?) 
or simply overwriting your conf/distributions file adding some commands
in there. So do not use this if you are paranoid, unless you are paranoid
enough to have checked the code of your libs, kernel and filesystems.
.TP
.B ignore \fR(for forward compatibility)
Ignore unknown ignore types given to \fI\-\-ignore\fP.
.TP
.B malformedchunk \fR(I hope you know what you do)
Do not stop when finding a line not starting with a space but
no colon(:) in it. These are otherwise rejected as they have no
defined meaning.
.TP
.B missingfield \fR(save to ignore)
Ignore missing fields in a .changes file that are only checked but
not processed. 
Those include: Format, Date, Urgency, Maintainer, Description, Changes
.TP
.B missingfile \fR(might be insecure)
When including a .dsc file from a .changes file,
try to get files needed but not listed in the .changes file
(e.g. when someone forgot to specify \-sa to dpkg\-buildpackage)
from the directory the .changes file is in instead of erroring out.
(\fB\-\-delete\fP will not work with those files, though.)
.TP
.B overlongcomments \fR(I hope you know what you do)
Allow overlong comments. That is a line started with a hash(#)
followed by lines starting with spaces. By default reprepro errors
out in that case, as marking every line as comment is as easy and
people might try to comment a single line within a multi-line
header (which does not work but makes all the rest a comment).
.TP
.B shortkeyid \fR(insecure)
Allow gpg-keys to be specified with less than 8 hexdigits of their fingerprint.
.TP
.B spaceonlyline \fR(I hope you know what you do)
Allow lines containing only (but non-zero) spaces. As these
do not separate chunks as thus will cause reprepro to behave
unexpected, they cause error messages by default.
.TP
.B surprisingarch
Do not reject a .changes file containing files for a
architecture not listed in the Architecture-header within it.
.TP
.B surprisingbinary
Do not reject a .changes file containing .deb files containing
packages whose name is not listed in the "Binary:" header
of that changes file.
.TP
.B unknownfield \fR(for forward compatibility)
Ignore unknown fields in the config files, instead of refusing to run
then.
.TP
.B unusedarch \fR(save to ignore)
No longer reject a .changes file containing no files for any of the
architectures listed in the Architecture-header within it.
.TP
.B wrongdistribution \fR(save to ignore)
Do not error out if a .changes file is to be placed in a
distribution not listed in that files' Distributions: header.
.TP
.B wrongsourceversion
Do not reject a .changes file containing .deb files with
a different opinion on what the version of the source package is.
.br
(Note: reprepro only compares literally here, not by meaning.)
.TP
.B wrongversion
Do not reject a .changes file containing .dsc files with
a different version.
.br
(Note: reprepro only compares literally here, not by meaning.)
.SH GUESSING
When including a binary or source package without explicitly
declaring a component with
.B \-C
it will take the
first component with the name of the section, being
prefix to the section, being suffix to the section
or having the section as prefix or any. (In this order)

Thus having specified the components:
"main non\-free contrib non\-US/main non\-US/non\-free non\-US/contrib"
should map e.g.
"non\-US" to "non\-US/main" and "contrib/editors" to "contrib",
while having only "main non\-free and contrib" as components should
map "non\-US/contrib" to "contrib" and "non\-US" to "main".

.B NOTE: 
Always specify main as the first component, if you want things 
to end up there.

.B NOTE: 
unlike in dak, non\-US and non\-us are different things...
.SH NOMENCLATURE
.B Codename 
the primary identifier of a given distribution. This are normally
things like \fBsarge\fP, \fBetch\fP or \fBsid\fP.
.TP
.B basename
the name of a file without any directory information.
.TP
.B filekey
the position relative to the mirrordir.  (as found as "Filename:" in Packages.gz)
.TP
.B "full filename"
the position relative to /
.TP
.B architecture
The term like \fBsparc\fP, \fBi386\fP, \fBmips\fP, ... .
To refer to the source packages, \fBsource\fP
is sometimes also treated as architecture.
.TP
.B component
Things like \fBmain\fP, \fBnon\-free\fP and \fBcontrib\fP
(by policy and some other programs also called section, reprepro follows
the naming scheme of apt here.)
.TP
.B section
Things like \fBbase\fP, \fBinterpreters\fP, \fBoldlibs\fP and \fBnon\-free/math\fP
(by policy and some other programs also called subsections).
.TP
.B md5sum
The checksum of a file in the format
"\fI<md5sum of file>\fP \fI<length of file>\fP"
.SH Some note on updates
.SS A version is not overwritten with the same version.
.B reprepro
will never update a package with a version it already has. This would
be equivalent to rebuilding the whole database with every single upgrade.
To force the new same version in, remove it and then update. 
(If files of
the packages changed without changing their name, make sure the file is
no longer remembered by reprepro. 
Without \fB\-\-keepunreferencedfiled\fP
and without errors while deleting it should already be forgotten, otherwise
a \fBdeleteunreferenced\fP or even some \fB__forget\fP might help.)
.SS The magic delete rule ("\-").
A minus as a single word in the
.B Update:
line of an distribution marks everything to be deleted. The mark causes later rules
to get packages even if they have (strict) lower versions. The mark will
get removed if a later rule sets the package on hold (hold is not yet implemented,
in case you might wonder) or would get a package with the same version 
(Which it will not, see above). If the mark is still there at the end of the processing,
the package will get removed.
.P
Thus the line "Update: \- 
.I rules
" will cause all packages to be exactly the
highest Version found in 
.I rules.
The line "Update: 
.I near 
\- 
.I rules
" will do the same, except if it needs to download packages, it might download
it from
.I near
except when too confused. (It will get too confused e.g. when 
.I near
or 
.I rules
have multiple versions of the package and the highest in
.I near
is not the first one in
.I rules,
as it never remember more than one possible spring for a package.
.P
Warning: This rule applies to all type/component/architecture triplets
of a distribution, not only those some other update rule applies to.
(That means it will delete everything in those!)
.SH ENVIRONMENT VARIABLES
Environment variables are always overwritten by command line options,
but overwrite options set in the \fBoptions\fP file. (Even when the
options file is obviously parsed after the environment variables as
the environment may determine the place of the options file).
.TP 
.B REPREPRO_BASE_DIR
The directory in this variable is used instead of the current directory,
if no \fB\-b\fP or \fB\-\-basedir\fP options are supplied.
.TP
.B REPREPRO_CONFIG_DIR
The directory in this variable is used when no \fB\-\-confdir\fP is
supplied.
.SH BUGS
Increased verbosity always shows those things one does not want to know.
(Though this might be inevitable and a corollary to Murphy)

While the source part is mostly considered as the architecture
.B source
some parts may still not use this notation.
.SH "WORK-AROUNDS TO COMMON PROBLEMS"
.TP
.B gpgme returned an impossible condition
With the woody version this normally meant that there was no .gnupg
directory in $HOME, but it created one and reprepro succeeds when called
again with the same command.
Since sarge the problem sometimes shows up, too. But it is no longer
reproducible and it does not fix itself, neither. Try running
\fBgpg \-\-verify \fP\fIfile-you-had-problems-with\fP manually as the
user reprepro is running and with the same $HOME. This alone might
fix the problem. It should not print any messages except perhaps
.br
gpg: no valid OpenPGP data found.
.br
gpg: the signature could not be verified.
.br
if it was an unsigned file.
.TP
.B not including .orig.tar.gz when a .changes file's version does not end in \-0 or \-1
If dpkg\-buildpackage is run without the \fB\-sa\fP option to build a version with
a Debian revision not being \-0 or \-1, it does not list the \fB.orig.tar.gz\fP file
in the \fB.changes\fP file.
If you want to \fBinclude\fP such a file with repepro
when the .orig.tar.gz file does not already exist in the pool, reprepro will report
an error.
This can be worked around by:
.br
call \fBdpkg\-buildpackage\fP with \fB\-sa\fP (recommended)
.br
copy the .orig.tar.gz file to the proper place in the pool before
.br
call reprepro with \-\-ignore=missingfile (discouraged)
.TP
.B leftover files in the pool directory.
reprepro is sometimes a bit too timid of deleting stuff. When things
go wrong and there have been errors it sometimes just leaves everything
where it is.
To see what files reprepro remembers to be in your pool directory but
does not know anything needing them right know, you can use
.br
\fBreprepro dumpunreferenced\fP
.br
To delete them:
.br
\fBreprepro deleteunreferenced\fP
.SH INTERRUPTING
Interrupting reprepro has its problems.
Some things (like speaking with apt methods, database stuff) can cause
problems when interrupted at the wrong time.
Then there are design problems of the code making it hard to distinguish
if the current state is dangerous or non-dangerous to interrupt.
Thus if reprepro receives a signal normally sent to tell a process to
terminate itself softly,
it continues its operation, but does not start any new operations.
(I.e. it will not tell the apt-methods any new file to download, it will
not replace a package in a target, unless it already had started with it,
it will not delete any files gotten dereferenced, and so on).

\fBIt only catches the first signal of each type. The second signal of a
given type will terminate reprepro. You will risk database corruption
and have to remove the lockfile manually.\fP

Also note that even normal interruption leads to code-paths mostly untested
and thus expose a multitude of bugs including those leading to data corruption.
Better think a second more before issuing a command than risking the need
for interruption.
.SH "REPORTING BUGS"
Report bugs or wishlist requests to <brlink@debian.org>
.br
or the Debian BTS (e.g. by using \fBreportbug reperepro\fP)
.SH COPYRIGHT
Copyright \(co 2004,2005,2006 Bernhard R. Link
.br 
This is free software; see the source for copying conditions. There is NO
warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.