tito/tito.props.5.asciidoc

tito.props(5)
============
include::man.asciidoc[]

NAME
----
tito.props - directives for tito(5) how to build package.


SYNOPSIS
--------
None
// older asciidoc versions (such as the version for .el5) require a synopsis section


DESCRIPTION
-----------
Project settings can be stored in files:

`GITROOT/rel-eng/tito.props`

`GITROOT/SOME/PACKAGE/tito.props`

The global rel-eng/tito.props is generally where settings are defined. For
some multi-project git repositories, individual packages can override these
settings by placing a tito.props in the project directory. (i.e. same location
as it's .spec file)


SECTIONS
--------
tito.props can contain several sections:


GLOBALCONFIG
------------
This section is mandatory. At least in tito.props as you need to specify
default builder and tagger for you project. You can use following variables:

default_builder::
The fully qualified Builder class implementation to use.
You can either specify builders shipped with tito(5) (see BUILDERS section
below), or a custom builder located within the directory your `lib_dir` option
points to.

default_tagger::
The fully qualified Tagger class implementation to use.
You can either specify builders shipped with tito(5) (see TAGGERS section
below), or a custom builder located within the directory your `lib_dir` option
points to.

lib_dir::
Optional property defining a directory to be added to the Python path when
executing tito. Allows you to store custom implementations of Builder, Tagger,
and Releaser.

changelog_format::
This option is used to control the formatting of entries when
generating changelog entries.  The default value is "%s (%ae)".  See
PRETTY FORMATS in git-log(1) for more information.

changelog_with_email::
If set to 0, then entries in changelog (subject of commits) are not
followed by email of commiter. Default is 1.  This option is
deprecated and provided for backwards-compatibility only.  New
configurations should consider changelog_format instead.

changelog_do_not_remove_cherrypick::
If set to 0, it will not remove from cherry picked commits the part "(cherry
picked from commit ...)"

tag_suffix::
An optional specification of a suffix to append to all tags created by tito
for this repo. Can be useful for situations where one git repository is
inheriting from another, but tags are created in both. The suffix will be an
indicator as to which repo the tag originated in. (i.e. tag_suffix = -mysuffix)


KOJI
----

disttag::
Dist tag variable, which is passed to rpmbuild for packages build in this tag.

blacklist::
Space separated list of packages, which should not be built in this tag.

whitelist::
If whitelist is present, only packages listed here can be built in this tag.
This also override blacklist.

scl::
Specify name of Software Collection into which package should be build.

CVS
---
cvsroot::
Root of your CVS repository. (i.e. cvsroot = :ext:myuser@cvs.fedoraproject.org:/cvs/extra)

branches::
CVS branches to sync sources to, and build from.
If you use zStreamTagger for EUS builds, use the format
 branches = BASE/EUS-VARIANT
for example:
 branches = RHEL-6/RHEL-6_1-Z
This will run "make zstreams" in BASE directory and will then use EUS-VARIANT
branch.

VERSION_TEMPLATE
----------------
Allows the user to write out a template file containing version and/or release and add it to git during the tagging process.

template_file::
Path to a file conforming to a Python string template. Path is relative to root of the entire git checkout, as this is likely to be stored in the top level rel-eng directory.

destination_file::
Specifies a file to write, relative to the directory for the package being tagged.

Example:

----
[version_template]
destination_file = version.txt
template_file = rel-eng/templates/version.rb
----



REQUIREMENTS
------------
tito::
If tito is older then specified version, it will refuse to continue.

BUILDCONFIG
-----------
builder::
This option is used in package specific tito.props only, and allows that
project to override the default_builder defined in rel-eng/tito.props.

tagger::
This option is used in package specific tito.props only, and allows that
project to override the default_tagger defined in rel-eng/tito.props.


TAGCONFIG
---------
require_package::
Comma separated list of packages, which needs to be installed prior tagging. If those
packages are not installed, tito will refuse to continue.

BUILDERS
--------

tito.builder.Builder::
Basic package builder. It create tar.gz of whole directory and create src.rpm
and build rpm using some supported method.

tito.builder.NoTgzBuilder::
Builder for packages that do not require the creation of tarball.
Usually these package have source files checked directly into git.

tito.builder.CvsBuilder::
Builder for packages whose sources are managed in dist-cvs/Fedora-cvs.

tito.builder.UpstreamBuilder::
Builder for packages that are based off an upstream git tag.
Commits applied in downstream git become patches applied to the upstream
tarball.
For example - you are building package foo-1.2-3... Tar.gz file is created from
commit, which is tagged by foo-1.2-1 and the diff between release 1 and 3 is
put in spec file as Patch0.

tito.builder.GemBuilder::
Builder for packages that list a .gem as Source0, the .gemspec shares a
directory hierarchy with the .spec file and the upstream does not want to check
.gem files into their git repository.

tito.distributionbuilder.DistributionBuilder::
Behave similar as tito.builder.UpstreamBuilder, but patch is created for every
release. Therefore package from previous example will end up with tar.gz file
created from tag foo-1.2-1 and with
 Patch0: foo-1.2-1-to-foo-1.2-2.patch
 Patch1: foo-1.2-1-to-foo-1.2-3.patch

TAGGERS
-------
All taggers which inherit fom tito.tagger.VersionTagger (all to this date),
will update file GITROOT/rel-eng/packages/name-of-package and put there one
line which consist of version-release of package, space delimiter, path to
package directory relative to GITROOT.

tito.tagger.VersionTagger::
Standard tagger class, used for tagging packages build from source in git.
Releaase will be tagged by incrementing the package version, and the actual
"Release" will be always set to 1.

tito.tagger.ReleaseTagger::
Keep version and increment release.

tito.zstreamtagger.zStreamTagger::
Tagger which increments zstream number in release. I.e. x.y.z-r%{dist}.Z+1
It is used for EUS packages.

tito.rheltagger.RHELTagger::
Tagger which is based on ReleaseTagger and uses Red Hat Enterprise Linux
changelog format:
- Resolves: #1111 - description
- Related: #1111 - description

RELEASER
--------
You can create section with the name same as releaser target and there you can
specify this option:

remote_git_name::
This is usefull for FedoraGitReleaser and DistGitReleaser and will allow you to
specify name of remote dist-git branch.
+
For example let say you have in releaser.conf:
 [git-sat]
 releaser = tito.release.DistGitReleaser
 branches = satellite-6.0-rhel-6
+
and then in package directory you can create tito.props with content:
 [git-sat]
 remote_git_name = ruby193-rubygem-simple-navigation
And it will push package into ruby193-rubygem-simple-navigation dist-git despite the
fact that it is in /rubygem-simple-navigation directory. And project name (as taken
from spec file) is rubygem-simple-navigation.

EXAMPLE
-------
 [globalconfig]
 default_builder = tito.builder.Builder
 default_tagger = tito.tagger.VersionTagger

 [koji]
 autobuild_tags = dist-5E-sw-1.2-candidate dist-f12-sw-1.2-candidate dist-f13-sw-1.2-candidate

 [dist-5E-sw-1.2-candidate]
 disttag = .el5

 [dist-f12-sw-1.2-candidate]
 disttag = .fc12
 blacklist=jabberd-selinux

 [dist-f13-sw-1.2-candidate]
 disttag = .fc13
 blacklist=jabberd-selinux

 [cvs]
 cvsroot = :gserver:your.dist-cvs.server.com:/cvs/dist
 branches = SATELLITE-5_4-RHEL-5

 [requirements]
 tito=0.3.0

SEE ALSO
--------
tito(8) titorc(5)


AUTHORS
-------
include::AUTHORS[]