reprepro manual

This manual documents reprepro, a tool to generate and administer Debian package repositories.
Other useful resources:

Table of contents

Sections of this document:

Introduction

What reprepro does

Reprepro is a tool to take care of a repository of Debian packages (.dsc,.deb and .udeb). It installs them to the proper places, generates indices of packages (Packages and Sources and their compressed variants) and of index files (Release and optionally Release.gpg), so tools like apt know what is available and where to get it from. It will keep track which file belongs to where and remove files no longer needed (unless told to not do so). It can also make (partial) partial mirrors of remote repositories, including merging multiple sources and automatically (if explicitly requested) removing packages no longer available in the source. And many other things (sometimes I fear it got a few features too much).

What reprepro needs

It needs some libraries (zlib, libgpgme, libdb (Version 3, 4.3 or 4.4)) and can be compiled with some more for additional features (libarchive, libbz2). Otherwise it only needs apt's methods (only when downloading stuff), gpg (only when signing or checking signatures), and if compiled without libarchive it needs tar and ar installed.
If you tell reprepro to call scripts for you, you will of course need the interpreters for these scripts: The included example to generate pdiff files needs python. The example to extract changelogs needs dpkg-source.

What this manual aims to do

This manual aims to give some overview over the most important features, so people can use them and so that I do not implement something a second time because I forgot support is already there. For a full reference of all possible commands and config options take a look at the man page, as this manual might miss some of the more obscure options.

First steps

generate a repository with local packages

mirroring packages from other repositories

This example shows how to generate a mirror of a single architecture with all packages of etch plus security updates:

Repository basics

An apt-getable repository of Debian packages consists of two parts: the index files describing what is available and where it is and the actual Debian binary (.deb), installer binary (.udeb), and source (.dsc together with .tar.gz or .orig.tar.gz and .diff.gz) packages.
While you do not know how these look like to use reprepro, it's always a good idea to know what you are creating.

Index files

All index files are in subdirectories of a directory called dists. Apt is very decided what names those should have, including the name of dists. Including all optional and extensional files, the hierarchy looks like this:
dists
CODENAME
Each distribution has it's own subdirectory here, named by it's codename.
Release
This file describes what distribution this is and the checksums of all index files included.
Release.gpg
This is the optional detached gpg signature of the Release file. Take a look at the section about signing for how to active this.
Contents-ARCHITECTURE.gz
This optional file lists all files and which packages they belong to. It's downloaded and used by tools like apt-file to allow users to determine which package to install to get a specific file.
To activate generating of these files by reprepro, you need a Contents header in your distribution declaration.
COMPONENT1
Each component has it's own subdirectory here. They can be named whatever users can be bothered to write into their sources.list, but things like main, non-free and contrib are common. But funny names like bad or universe are just as possible.
source
If this distribution supports sources, this directory lists which source packages are available in this component.
Release
This file contains a copy of those information about the distribution applicable to this directory.
Sources
Sources.gz
Sources.bz2
These files contain the actual description of the source Packages. By default only the .gz file created, to create all three add the following to the declarations of the distributions: 
DscIndices Sources Release . .gz .bz2
That header can also be used to name those files differently, but then apt will no longer find them...
Sources.diff
This optional directory contains diffs, so that only parts of the index file must be downloaded if it changed. While reprepro cannot generate these so-called pdiffs itself, it ships both with a program called rredtool and with an example python script to generate those.
binary-ARCHITECTURE
Each architecture has its own directory in each component.
Release
This file contains a copy of those information about the distribution applicable to this directory.
Packages
Packages.gz
Packages.bz2
These files contain the actual description of the binary Packages. By default only the uncompressed and .gz files are created. To create all three, add the following to the declarations of the distributions: 
DebIndices Packages Release . .gz .bz2
That header can also be used to name those files differently, but then apt will no longer find them...
Packages.diff
This optional directory contains diffs, so that only parts of the index file must be downloaded if it changed. While reprepro cannot generate these so-called pdiffs itself, it ships both with a program called rredtool and with an example python script to generate those.
debian-installer
This directory contains information about the .udeb modules for the Debian-Installer. Those are actually just a very stripped down form of normal .deb packages and this the hierarchy looks very similar:
binary-ARCHITECTURE
Packages
Packages.gz
COMPONENT2
There is one dir for every component. All look just the same.
SUITE -> CODENAME
To allow accessing distribution by function instead of by name, there are often symbolic links from suite to codenames. That way users can write 
deb http://some.domain.tld/debian SUITE COMPONENT1 COMPONENT2
instead of 
deb http://some.domain.tld/debian CODENAME COMPONENT1 COMPONENT2
in their /etc/apt/sources.list and totally get surprised by getting something new after a release.

Package pool

While the index files have a required filename, the actual files are given just as relative path to the base directory you specify in your sources list. That means apt can get them no matter what scheme is used to place them. The classical way Debian used till woody was to just put them in subdirectories of the binary-ARCHITECTURE directories, with the exception of the architecture-independent packages, which were put into a artificial binary-all directory. This was replaced for the official repository with package pools, which reprepro also uses. (Actually reprepro stores everything in pool a bit longer than the official repositories, that's why it recalculates all filenames without exception).
In a package pool, all package files of all distributions in that repository are stored in a common directory hierarchy starting with pool/, only separated by the component they belong to and the source package name. As everything this has disadvantages and advantages: Now let's look at the actual structure of a pool (there is currently no difference between the pool structure of official Debian repositories and those generated by reprepro):
pool
The directory all this resides in is normally called pool. That's nowhere hard coded in apt but that only looks at the relative directory names in the index files. But there is also no reason to name it differently.
COMPONENT1
Each component has it's own subdirectory here. They can be named whatever users can be bothered to write into their sources.list, but things like main, non-free and contrib are common. But funny names like bad or universe are just as possible.
a
As there are really many different source packages, the directory would be too full when all put here. So they are separated in different directories. Source packages starting with lib are put into a directory named after the first four letters of the source name. Everything else is put in a directory having the first letter as name.
asource
Then the source package name follows. So this directory pool/COMPONENT1/a/asource/ would contain all files of different versions of the hypothetical package asource.
asource
a-source_version.dsc
a-source_version.tar.gz
The actual source package consists of its description file (.dsc) and the files references by that.
binary_version_ARCH1deb
binary_version_ARCH2.deb
binary2_version_all.deb
di-module_version_ARCH1.udeb
Binary packages are stored here to. So to know where a binary package is stored you need to know what its source package name is.
liba
As described before packages starting with lib are not stored in l but get a bit more context.
COMPONENT2
There is one dir for every component. All look just the same.
As said before, you don't need to know this hierarchy in normal operation. reprepro will put everything to where it belong, keep account what is there and needed by what distribution or snapshot, and delete files no longer needed. (Unless told otherwise or when you are using the low-level commands).

Config files

Configuring a reprepro repository is done by writing some config files into a directory. This directory is currently the conf subdirectory of the base directory of the repository, unless you specify --confdir or set the environment variable REPREPRO_CONFIG_DIR.
options
If this file exists, reprepro will consider each line an additional command line option. Arguments must be in the same line after an equal sign. Options specified on the command line take precedence.
distributions
This is the main configuration file and the only that is needed in all cases. It lists the distributions this repository contains and their properties.
See First steps for a short example or the manpage for a list of all possible fields.
updates
Rules about where to download packages from other repositories. See the section Mirroring / Updating for more examples or the man page for a full reference.
pulls
Rules about how to move packages in bulk between distributions where to download packages from other repositories. See the section Propagation of packages for an example or the man page for full reference.
incoming
Rules for incoming queues as processed by processincoming. See Processing an incoming queue for more information.

Generation of index files

Deciding when to generate

As reprepro stores all state in its database, you can decide when you want them to be written to the dists/ directory. You can always tell reprepro to generate those files with the export command: 
reprepro -b $YOURBASEDIR export $CODENAMES
This can be especially useful, if you just edited conf/distributions and want to test what it generates.

While that command regenerates all files, in normal operation reprepro will only regenerate files where something just changed or that are missing. With --export option you can control when this fill happen:

never
Don't touch any index files. This can be useful for doing multiple operations in a row and not wanting to regenerate the indices all the time. Note that unless you do an explicit export or change the same parts later without that option, the generated index files may be permanently out of date.
silent-never
Like never, but be more silent about it.
changed
This is the default behaviour since 3.0.1. Only export distributions where something changed (and no error occurred that makes an inconsistent state likely). And in those distributions only (re-)generate files which content should have been changed by the current action or which are missing.
lookedat
New name for normal since 3.0.1.
normal
This was the default behaviour until 3.0.0 (changed in 3.0.1). In this mode all distributions are processed that were looked at without error (where error means only errors happening while the package was open so have a chance to cause strange contents). This ensures that even after a operation that had nothing to do the looked at distribution has all the files exported needed to access it. (But still only files missing or that content would change with this action are regenerated).
force
Also try to write the current state if some error occurred. In all other modes reprepro will not write the index files if there was a problem. While this keeps the repository usable for users, it means that you will need an explicit export to write possible other changes done before that in the same run. (reprepro will tell you that at the end of the run with error, but you should not miss it).

Distribution specific fields

There are a lot of conf/distributions headers to control what index files to generate for some distribution, how to name them, how to postprocess them and so on. The most important are:

Fields for the Release files

The following headers are copied verbatim to the Release file, if they exist: Origin, Label, Codename, Suite, Architectures (excluding a possible value "source"), Components, Description, and NotAutomatic, ButAutomaticUpgrades.

Choosing compression and file names

Depending on the type of the index files, different files are generated. No specifying anything is equivalent to: 
 DscIndices Sources Release .gz
 DebIndices Packages Release . .gz
 UDebIndices Packages . .gz
This means to generate Release, Sources.gz for sources, Release, Packages and Packages.gz for binaries and Packages and Packages.gz for installer modules.
The format of these headers is the name of index file to generate, followed by the optional name for a per-directory release description (when no name is specified, no file is generated). Then a list of compressions: A single dot (.) means generating an uncompressed index, .gz means generating a gzipped output, while .bz2 requests and bzip2ed file. (.bz2 is not available when disabled at compile time). After the compressions a script can be given that is called to generate/update additional forms, see "Additional index files".

Signing

If there is a SignWith header, reprepro will try to generate a Release.gpg file using libgpgme. If the value of the header is yes it will use the first key it finds, otherwise it will give the option to libgpgme to determine the key. (Which means fingerprints and keyids work fine, and whatever libgpgme supports, which might include most that gpg supports to select a key).
The best way to deal with keys needing passphrases is to use gpg-agent. The only way to specify which keyring to use is to set the GNUPGHOME environment variable, which will effect all distributions.

Contents files

Reprepro can generate files called dists/CODENAME/Contents-ARCHITECTURE.gz listing all files in all binary packages available for the selected architecture in that distribution and which package they belong to.
This file can either be used by humans directly or via downloaded and searched with tools like apt-file.
To activate generating of these files by reprepro, you need a Contents header in that distribution's declaration in conf/distributions, like: 
Contents:
Versions before 3.0.0 need a ratio number there, like: 
Contents: 1
The number is the inverse ratio of not yet looked at and cached files to process in every run. The larger the more packages are missing. 1 means to list everything.
The arguments of the Contents field and other fields control which Architectures to generate Contents files for and which Components to include in those. For example 
Contents: udebs nodebs . .gz .bz2
ContentsArchitectures: ia64
ContentsComponents:
ContentsUComponents: main
means to not skip any packages, generate Contents for .udeb files, not generating Contents for .debs. Also it is only generated for the ia64 architecture and only packages in component main are included.

Additional index files (like .diff)

Index files reprepro cannot generate itself, can be generated by telling it to call a script.
using rredtool to generate pdiff files
Starting with version 4.1.0, the rredtool coming with reprepro can be used as hook to create and update Packages.diff/Index files.
Unlike dak (which created the official Debian repositories) or the pdiff.py script (see below) derived from dak, an user will only need to download one of those patches, as new changes are merged into the old files.
To use it, make sure you have diff and gzip installed. Then add something like the following to the headers of the distributions that should use this in conf/distributions: 
 DscIndices: Sources Release . .gz /usr/bin/rredtool
 DebIndices: Packages Release . .gz /usr/bin/rredtool
the pdiff example hook script (generates pdiff files)
This example generates Packages.diff and/or Sources.diff directories containing a set of ed-style patches, so that people do not redownload the whole index for just some small changes.
To use it, copy pdiff.example from the examples directory into your conf directory. (or any other directory, then you will need to give an absolute path later). Unpack, if needed. Rename it to pdiff.py and make it executable. Make sure you have python3-apt, diff and gzip installed. Then add something like the following to the headers of the distributions that should use this in conf/distributions: 
 DscIndices: Sources Release . .gz pdiff.py
 DebIndices: Packages Release . .gz pdiff.py
More information can be found in the file itself. You should read it.
the bzip2 example hook script
This is an very simple example. Simple and mostly useless, as reprepro has built in .bz2 generation support, unless you compiled it your own with --without-libbz2 or with no libbz2-dev installed.
To use it, copy bzip.example from the examples directory into your conf directory. (or any other directory, then you will need to give an absolute path later). Unpack, if needed. Rename it to bzip2.sh and make it executable. Then add something like the following to the headers of the distributions that should use this in conf/distributions: 
 DscIndices: Sources Release . .gz bzip2.sh
 DebIndices: Packages Release . .gz bzip2.sh
 UDebIndices: Packages . .gz bzip2.sh
The script will compress the index file using the bzip2 program and tell reprepro which files to include in the Release file of the distribution.
internals
TO BE CONTINUED

...

TO BE CONTINUED

Local packages

There are two ways to get packages not yet in any repository into yours.
includedsc, includedeb, include
These are for including packages at the command line. Many options are available to control what actually happens. You can easily force components, section and priority and/or choose to include only some files or only in specific architectures. (Can be quite useful for architecture all packages depending on some packages you will some time before building for some of your architectures). Files can be moved instead of copied and most sanity checks overwritten. They are also optimized towards being fast and simply try things instead of checking a long time if they would succeed.
processincoming
This command checks for changes files in an incoming directory. Being optimized for automatic processing (i.e. trying to checking everything before actually doing anything), it can be slower (as every file is copied at least once to sure the owner is correct, with multiple partitions another copy can follow). Component, section and priority can only be changed via the distribution's override files. Every inclusion needs a .changes file.
This method is also relatively new (only available since 2.0.0), thus optimisation for automatic procession will happen even more.

Including via command line

There are three commands to directly include packages into your repository: includedeb, includedsc and includechanges. Each needs to codename of the distribution you want to put your package into as first argument and a file of the appropriate type (.deb, .dsc or .changes, respectively) as second argument.
If no component is specified via --component (or short -C), it will be guessed looking at its section and the components of that distribution.
If there are no --section (or short -S) option, and it is not specified by the (binary or source, depending on the type) override file of the distribution, the value from the .changes-file is used (if the command is includechanges) or it is extracted out of the file (if it is a .deb-file, future versions might also try to extract it from a .dsc's diff or tarball).
Same with the priority and the --priority (or short -P) option.
With the --architecture (or short -A) option, the scope of the command is limited to that architecture. includdeb will add a Architecture all packages only to that architecture (and complain about Debian packages for other architectures). include will do the same and ignore packages for other architectures (source packages will only be included if the value for --architecture is source).
To limit the scope to a specify type of package, use the --packagetype or short -T option. Possible values are deb, udeb and dsc.
When using the --delete option, files will be moved or deleted after copying them. Repeating the --delete option will also delete unused files.
TO BE CONTINUED.

Processing an incoming queue

Using the processincoming command reprepro can automatically process incoming queues. While this is still improveable (reprepro still misses ways to send mails and especially an easy way to send rejection mails to the uploader directly), it makes it easy to have an directory where you place your packages and reprepro will automatically include them.
To get this working you need three things:

The file conf/incoming

 describes the different incoming queues. As usual the different chunks are separated by empty lines. Each chunk can have the following fields:
Name
This is the name of the incoming queue, that processincoming wants as argument.
IncomingDir
The actual directory to look for .changes files.
TempDir
To ensure integrity of the processed files and their permissions, every file is first copied from the incoming directory to this directory. Only the user reprepro runs as needs write permissions here. It speeds things up if this directory is in the same partition as the pool.
Allow
This field lists the distributions this incoming queue might inject packages into. Each item can be a pair of a name of a distribution to accept and a distribution to put it into. Each upload has each item in its Distribution: field compared first to last to each of this items and is put in the first distribution accepting it. For example 
Allow: stable>etch stable>etch-proposed-updates mystuff unstable>sid
will put a .changes file with Distribution: stable into etch. If that is not possible (e.g. because etch has a UploadersList option not allowing this) it will be put into etch-proposed-updates. And a .changes file with Distribution: unstable will be put into sid, while with Distribution: mystuff will end up in mystuff.
If there is a Default field, the Allow field is optional.
Default
Every upload not caught by an item of the Allow field is put into the distribution specified by this.
If there is a Allow field, the Default field is optional.
Multiple
This field only makes a difference if a .changes file has multiple distributions listed in its Distribution: field. Without this field each of those distributions is tried according to the above rules until the package is added to one (or none accepts it). With this field it is tried for each distribution, so a package can be upload to multiple distributions at the same time.
Permit
A list of options to allow things otherwise causing errors. (see the manpage for possible values).
This field os optional.
Cleanup
Determines when and what files to delete from the incoming queue. By default only successfully processed .changes files and the files references by those are deleted. For a list of possible options take a look into the man page.
This field os optional.

conf/distribution for processincoming

 There are no special requirements on the conf/distribution file by processincoming. So even a simple 
Codename: mystuff
Architectures: i386 source
Components: main non-free contrib bad
will work.
The Uploaders field can list a file limiting uploads to this distribution to specific keys and AlsoAcceptFor is used to resolve unknown names in conf/incoming's Allow and Default fields.

Getting processincoming called.

 While you can just call reprepro processincoming manually, having an incoming queue needing manual intervention takes all the fun out of having an incoming queue, so usually so automatic way is chosen:

Mirroring / Updating

Reprepro can fetch packages from other repositories. For this it uses apt's methods from /usr/lib/apt/methods/ so everything (http, ftp, ...) that works with apt should also work with reprepro. Note that this works on the level of packages, even though you can tell reprepro to create a distribution having always the same packages as some remote repository, the repository as a whole may not look exactly the same but only have the same set of packages in the same versions.
You can also only mirror a specific subset of packages, merge multiple repositories into one distribution, or even have distributions mixing remote and local packages.
Each distribution to receive packages from other repositories needs an Update: field listing the update rules applied to it. Those update rules are listed in conf/updates. There is also the magic - update rule, which tells reprepro to delete all packages not re-added by later rules.
To make reprepro to update all distributions call reprepro update without further arguments, or give the distributions to update as additional arguments.
Let's start with some examples:

Updating examples

Let's assume you have the following conf/distributions 
Codename: etch
Architectures: i386 source
Components: main contrib
Update: local - debian security

Codename: mystuff
Architectures: abacus source
Components: main bad
Update: debiantomystuff
and the following conf/updates 
Name: local
Method: http://ftp.myorg.tld/debian

Name: debian
Method: http://ftp.de.debian.org/debian
VerifyRelease: A70DAF536070D3A1
Config: Acquire::Http::Proxy=http://proxy.yours.org:8080

Name: security
Suite: */updates
Method: http://security.eu.debian.org/
Fallback: http://security.debian.org/
VerifyRelease: A70DAF536070D3A1
Config: Acquire::Http::Proxy=http://proxy.yours.org:8080

Name: debiantomystuff
Suite: sid
Method: http://ftp.de.debian.org/debian
Architectures: i386>abacus source
Components: main non-free>bad contrib>bad
FilterFormula: Architecture (== all)| !Architecture
FilterList: deinstall list
and a file conf/list with some output as dpkg --get-selections is printing.
If you then run reprepro update etch or reprepro checkupdate etch, reprepro looks at etch's Update: line and finds four rules. The first is the local rule, which only has a method, so that means it will download the Release file from http://ftp.myorg.tld/debian/dists/etch/Release and (unless it already has downloaded them before or that repository does not have all of them) downloads the binary-i386/Packages.gz and source/Sources.gz files for main and contrib. The same is done for the debian and security rules. As they have a VerifyRelease field, Release.gpg is also downloaded and checked to be signed with the given key (which you should have imported to you gpg keyring before). As security has a Suite: field, not the codename, but the content of this field (with an possible* replaced by the codename), is used as distribution to get.
Then it will parse for each part of the distribution, parse the files it get from left to right. For each package it starts with the version currently in the distribution, if there is a newer on in local it will mark this. Then there is the delete rule -, which will mark it to be deleted (but remembers what was there, so if later the version in the distribution or the version in local are newest, it will get them from here avoiding slow downloads from far away). Then it will look into debian and then in security, if they have a newer version (or the same version, clearing the deletion mark).
If you issued checkupdate reprepro will print what it would do now, otherwise it tries to download all the needed files and when it got all, change the packages in the distribution to the new ones, export the index files for this distribution and finally delete old files no longer needed.
TO BE CONTINUED.

Propagation of packages

You can copy packages between distributions using the pull and copy commands.
With the copy command you can copy packages by name from one distribution to the other within the same repository.
With the pull command you can pull all packages (or a subset defined by some list, or exceptions by some list, or by some formula, or ...) from one distribution to another within the same formula.
Note that both assume the filenames of the corresponding packages in the pool will not differ, so you cannot move packages from one component to another.
Let's just look at a little example, more information can be found in the man page.
Assume you upload all new packages to a distribution and you want another so you can keep using an old version until you know the newer works, too. One way would be to use something like the following conf/distributions: 
Codename: development
Suite: unstable
Components: main extra
Architectures: i386 source

Codename: bla
Suite: testing
Components: main extra
Architectures: i386 source
Pull: from_development
and conf/pulls: 
Name: from_development
From: development
i.e. you have two distributions, bla and development. Now you can just upload stuff to development (or it's alias unstable). And when you want a single package to go to testing, you can use the copy command: 
reprepro copy bla development name1 name2 name3
If you do not want to copy all packages of a given name, but only some of them, you can use -A, -T and -C: 
reprepro -T deb -A i386 copy bla development name1
will copy .deb packages called name1 from the i386 parts of the distribution.
TO BE CONTINUED

Snapshots

There is a gensnapshot command.
TO BE DOCUMENTED

Source package tracking

TO BE DOCUMENTED

Extending reprepro / Hooks and more

When reprepro misses some functionality, it often can be added by some kind of hook.
Currently you can execute your own scripts at the following occasions:

Scripts to be run when adding or removing packages

Whenever a package is added or removed, you can tell reprepro to log that to some file and/or call a script using the Log: directive in conf/distributions.
This script can send out mails and do other logging stuff, but despite the name, it is not restricted to logging.

Automatically extracting changelog and copyright information

reprepro ships with an example script to extract debian/changelog and debian/copyright files from source packages into a hierarchy loosely resembling the way changelogs are made available at http://packages.debian.org/changelogs/.
All you have to do is to copy (or unpack if compressed) the file changelogs.example from the examples directory in the reprepro source or /usr/share/doc/reprepro/examples/ of your installed reprepro package into your conf/ directory (or somewhere else, then you will need an absolute path later), perhaps change some directories specified in it and add something like the following lines to all distributions in conf/distributions that should use this feature: 
Log:
 --type=dsc changelogs.example
If you still want to log to some file, just keep the filename there: 
Log: mylogfilename
 --type=dsc changelogs.example
Then cause those files to be generated for all existing files via 
reprepro rerunnotifiers
and all future source packages added or removed will get this list automatically updated.

Writing your own Log: scripts

You can list an arbitrary amount of scripts, to be called at specified times (which can overlap or even be the same): 
Log: logfilename
 --type=dsc script-to-run-on-source-package-changes
 script-to-run-on-package-changes
 another-script-to-run-on-package-changes
 --type=dsc --component=main script-to-run-on-main-source-packages
 --architecture=i386 --type=udeb script-to-run-on-i386-udebs
 --changes script-to-run-on-include-or-processincoming
There are two kind of scripts: The first one is called when a package was added or removed. Using the --archtecture=, --component= and --type= options you can limit it to specific parts of the distribution. The second kind is marked with --changes and is called when a .changes-file was added with include or processincoming. Both are called asynchronous in the background after everything was done, but before no longer referenced files are deleted (so the files of the replaced or deleted package are still around).
Calling conventions for package addition/removal scripts
This type of script is called with a variable number of arguments. The first argument is the action. This is either add, remove or replace. The next four arguments are the codename of the affected distribution and the packagetype, component and architecture in that distribution affected. The sixth argument is the package's name. After that is the version of the added package (add and replace) and the version of the removed package (remove and replace). Finally the filekeys of the new (add and replace) and/or removed (remove and replace) package are listed starting with the marker "--" followed by each filekey (the name of the file in the pool/ relative to REPREPRO_OUT_DIR) as its own argument.
The environment variable REPREPRO_CAUSING_COMMAND contains the command of the action causing this change. The environment variable REPREPRO_CAUSING_FILE contains the name of the file given at the command line causing this package to be changed, if there is one. (i.e. with includedeb, includedsc and include). The environment variables REPREPRO_CAUSING_RULE and REPREPRO_FROM are the name of the update or pull rule pulling in a package and the name of the distribution a package is coming from. What this name is depends on the command and for most commands it is simply not set at all. And of course all the REPREPRO_*_DIR variables are set.
Calling conventions for .changes scripts
This type of script is called with 5 or 6 arguments. The first is always "accepted", to make it easier to check it is configured the right way. The second argument is the codename of the distribution the .changes-file was added to. The third argument is the source name, the forth the version. The fifth name is the .changes itself (in case of processingcoming the secure copy in the temporary dir). There is a sixth argument if the .changes-file was added to the pool/: The filekey of the added .changes file (i.e. the filename relative to REPREPRO_OUT_DIR).
The environment variable REPREPRO_CAUSING_COMMAND contains the command of the action causing this change. The environment variable REPREPRO_CAUSING_FILE contains the name of the file given at the command line, if there is one (e.g. with include). And of course all the REPREPRO_*_DIR variables are set.

Scripts to be run to process byhand files

.changes files can (beside the usual packages files to be included in the repository) contain additional files to be processed specially. Those are marked by the special section byhand (in Debian) or raw-something (in Ubuntu). Besides storing them just in the pool besides the packages using the includebyhand value in the Tracking settings you can also let reprepro process a hook to process them when encountering them in the processincomming action (Typical usages are uploading documentation files this way that are unpacked next to the repository, or installer images or stuff like that). To use them add to the distribution's defining stanca in conf/distributions a field like: 
ByhandHooks:
 byhand * manifesto.txt handle-byhand.sh
This will call the hook script handle-byhand.sh for every byhand file with section byhand, any priority and filename manifesto.txt. (The first three fields allow glob characters for matching). The script will then be called with 5 arguments: the codename of the distribution, the section, the priority, the filename as found in the changes file and the filename of where the script can find the actual file.

Scripts to be run when creating index files (Packages.gz, Sources.gz)

this hook is described in the section "Additional index files".

Scripts to be run when signing releases

Instead of creating InRelease and Release.gpg files using libgpgme, the SignWith option can also contain a exclamation mark followed by a space and the name of a hook script to call. The script gets three arguments: The filename to sign, the filename of the InRelease file to create and the filename of the Release.gpg to create (a Release.gpg does not need to be created. reprepro will assume you do not care about that legacy file if it is not created). Reprepro will wait for the script to continue and only do the renaming and deleting of old files after that, so the script might wait for example for someone to copy files from the system, signing and copying them it, for example.

Scripts to be run after changing the visible files of the repository managed

When using the --outhook command line option (or the corresponding outhook in the options file), reprepro will create a .outlog file in the log directory describing any changes done to the out dir and calls the hook script given as argument with this file as argument. The .outlog file consists of lines each starting with a keyword and then some arguments separated by tab characters. The possible keywords are: All POOLNEW come before any distribution changes referencing them and all POOLDELETE will be afterwards. Each line belonging to a distribution is guaranteed to be between the corresponding START-DISTRIBUTION and END-DISTRIBUTION or between a START-SNAPSHOT and END-SNAPSHOT or between a with the same directory (i.e. there is some redundancy so you can choose to parse the information where it is more convenient for you). The lines starting with DIST describe new or modified files in the distribution description exported by reprepro. No hint is given if that file was previously non-existent, a proper file or a symlink (i.e. if you copy stuff, do not make any assumptions about that). Future versions of reprepro might create DISTKEEP lines to denote files that have not changed (i.e. just ignore those lines to be future-proof). The directories for the distribution entries are what apt expects them (i.e. always starting with dists/, while the third argument to DISTFILE is the name reprepro generated (i.e. starts with the distdir value, which can be configured to not end with dists/).

when reprepro finished

With the --endhook command line option (or the corresponding endhook in the options file) you can specify a hook to be executed after reprepro finished but before reprepro returns the to calling process. The hook gets all the command line arguments after the options (i.e. starting with the name of the action) and the exit code reprepro would have produces. For an example see the man page.

Maintenance

This section lists some commands you can use to check and improve the health of you repository.
Normally nothing of this should be needed, but taking a look from time to time cannot harm. 
reprepro -b $YOURBASEDIR dumpunreferenced
This lists all files reprepro knows about that are not marked as needed by anything. Unless you called reprepro with the --keepunreferenced option, those should never occur. Though if reprepro is confused or interrupted it may sometimes prefer keeping files around instead of deleting them. 
reprepro -b $YOURBASEDIR deleteunreferenced
This is like the command before, only that such files are directly forgotten and deleted. 
reprepro -b $YOURBASEDIR check
Look if all needed files are in fact marked needed and known. 
reprepro -b $YOURBASEDIR checkpool
Make sure all known files are still there and still have the same checksum. 
reprepro -b $YOURBASEDIR checkpool fast
As the command above, but do not compute checksums. 
reprepro -b $YOURBASEDIR tidytracks
If you use source package tracking, check for files kept because of this that should no longer by the current rules.
If you fear your tracking data could have became outdated, you can also try the retrack command: 
reprepro -b $YOURBASEDIR retrack
That refreshes the tracking information about packages used and then runs a tidytracks. (Beware: don't do this with reprepro versions before 3.0.0).

Internals

reprepro stores the data it collects in Berkeley DB file (.db) in a directory called db/ or whatever you specified via command line. With a few exceptions, those files are NO CACHES, but the actual data. While some of those data can be regained when you lose those files, they are better not deleted.

packages.db

This file contains the actual package information.
It contains a database for every (codename,component,architecture,packagetype) quadruple available.
Each is indexed by package name and essentially contains the information written do the Packages and Sources files.
Note that if you change your conf/distributions to no longer list some codenames, architectures or components, that will not remove the associated databases in this file. That needs an explicit call to clearvanished.

references.db

This file contains a single database that lists for every file why this file is still needed. This is either an identifier for a package database, an tracked source package, or a snapshot.
Some low level commands to access this are (take a look at the manpage for how to use them):
rereference
recreate references (i.e. forget old and create newly)
dumpreferences
print a list of all references
_removereferences
remove everything referenced by a given identifier
_addreference
manually add a reference
_addreferences
manually add multiple references

files.db / checksums.db

These files contains what reprepro knows about your pool/ directory, i.e. what files it things are there with what sizes and checksums. The file files.db is used by reprepro before version 3.3 and kept for backwards compatibility. If your repository was only used with newer versions you can safely delete it. Otherwise you should run collectnewchecksums before deleting it. The file checksums.db is the new file used since version 3.3. It can store more checksums types (files.db only contained md5sums, checksums.db can store arbitrary checksums and reprepro can even cope with it containing checksum types it does not yet know of) but for compatibility with pre-3.3 versions is not the canonical source of information as long as a files.db file exists).
If you manually put files in the pool or remove them, you should tell reprepro about that. (it sometimes looks for files there without being told, but it never forgets files except when it would have deleted them anyway). Some low level commands (take a look at the man page for how to use them):
collectnewchecksums
Make sure every file is listed in checksums.db and with all checksum types your reprepro supports.
checkpool fast
Make sure all files are still there.
checkpool
Make sure all files are still there and correct.
dumpunreferenced
Show all known files without reference.
deleteunreferenced
Delete all known files without reference.
_listmd5sums
Dump this database (old style)
_listchecksums
Dump this database (new style)
_detect
Add files to the database
_forget
Forget that some file is there
_addmd5sums
Create the database from dumped data
_addchecksums
dito

release.cache.db

In this file reprepro remembers what it already wrote to the dists directory, so that it can write their checksums (including the checksums of the uncompressed variant, even if that was never written to disk) in a newly to create Release file without having to trust those files or having to unpack them.

contents.cache.db

This file contains all the lists of files of binary package files where reprepro already needed them. (which can only happen if you requested Contents files to be generated).

tracking.db

This file contains the information of the source package tracking.

Disaster recovery

TO BE DOCUMENTED (see the recovery file until then)

Paranoia

As all software, reprepro might have bugs. And it uses libraries not written by myself, which I'm thus even more sure that they will have bugs. Some of those bugs might be security relevant. This section contains some tips, to reduce the impact of those. External stuff being used and attack vectors opened by it:
libgpgme/gpg
Almost anything is run through libgpgme and thus gpg. It will be used to check the Release.gpg file, or to read .dsc and .changes files (even when there is no key to look for specified, as that is the best way to get the data from the signed block). Avoiding this by just accepting stuff without looking for signatures on untrusted data is not really an option, so I know nothing to prevent this type of problems.
libarchive
The .tar files within .deb files are normally (unless that library was not available while compiling) read using libarchive. This happens when a .deb file is to be added (though only after deciding if it should be added, so if it does not have the correct checksum or the .changes did not have the signatures you specified, it is not) or when the file list is to be extracted (when creating Contents files). Note that they are not processed when only mirroring them (of course unless Contents files are generated), as then only the information from the Packages file is copied.
dpkg-deb/tar
If reprepro was compiled without libarchive, dpkg-deb is used instead, which most likely will call tar. Otherwise just the same like the last item.
zlib
When mirroring packages, the downloaded Packages.gz and Sources.gz files are read using zlib. Also the generated .gz files are generated using it. There is no option but hoping there is no security relevant problem in that library.
libbz2
Only used to generate .bz2 files. If you fear simple blockwise writing using that library has a security problem that can be exploited by data enough harmless looking to be written to the generated index files, you can always decide to no tell reprepro to generate .bz2 files.

What reprepro cannot do

There are some things reprepro does not do:
Verbatim mirroring
Reprepro aims to put all files into a coherent pool/ hierarchy. Thus it cannot guarantee that files will have the same relatives path as in the original repository (especially if those have no pool). It also creates the index files from its own indices. While this leads to a tidy repository and possible savings of disk-space, the signatures of the repositories you mirror cannot be used to authenticate the mirror, but you will have to sign (or tell reprepro to sign for you) the result. While this is perfect when you only mirror some parts or specific packages or also have local packages that need local signing anyway, reprepro is no suitable tool for creating a full mirror that can be authenticated without adding the key of this repository.
Placing your files on your own
Reprepro does all the calculation of filenames to save files as, bookkeeping what files are there and what are needed and so on. This cannot be switched off or disabled. You can place files where reprepro will expect them and reprepro will use them if their md5sum matches. But reprepro is not suited if you want those files outside of a pool or in places reprepro does not consider their canonical ones.
Having different files with the same name
take a look in the FAQ (currently question 1.2) why and how to avoid the problem.