Tito is a tool for managing RPM based projects using git for their source code repository.
Tito offers the following features:
- Tag new releases with incremented RPM version or release.
- Auto-generate spec file changelog based on git history since last tag.
- Create reliable tar.gz's with consistent checksums from any tag.
- Build source and binary rpms off any tag.
- Build source and binary "test" rpms off most recently committed code.
- Build multiple source rpms with appropriate disttag's for submission to the Koji build system
- On a per-branch basis in git:
- Maintain concurrent version streams.
- Vary the way packages are built/tagged.
- Report on any diffs or commits messages missing since last tag.
- Build packages off an "upstream" git repository, where modifications in the "downstream" git repository will be applied as a patch in the source rpm.
- Manage all of the above for a git repository with many disjoint packages within it.
From your git repository:
This will create a top-level metadata directory called "rel-eng/" and commit it to git. This directory will store tito's configuration and package metadata on a per branch basis. It will be filtered out when creating .tar.gz's.
Before doing most everything you'll need to tag your package(s).
Before doing this you'll need to ensure that your package spec files are at the top of the relative source tree for that package.
For the most common case, a single project git repository:
mypackage.spec rel-eng/ src/
For a multi-project git repository, something like:
rel-eng/ package1/ mypackage.spec src/ subdir/ package2/ anotherpkg.spec src/
The packages can be organized in any hierarchy you like and even be moved around and re-tagged, we only need to have the spec file at the top of the source for that package.
To create an initial package tag, modify your spec file's version/release as desired and run, add a changelog entry, and run:
tito tag --keep-version --no-auto-changelog
For future tagging you'll probably want to use the auto-changelog, which will auto-populate based on the first line of every git commit since your last package tag, then give you a chance to edit it.
By default if you omit --keep-version, tito will tag by bumping the rpm version. (i.e. we bump the Z in X.Y.Z. If you'd prefer to bump the package release instead (normally should just be used for changes to the spec file or patches applied within it), you can change the default_tagger class in rel-eng/tito.props to ReleaseTagger. This will affect all packages in this git branch, if you'd prefer to do this on a per-package basis you can do so in a package specific tito.props. (see section below)
Once a package is tagged you will need to push both the auto-commit and the tag to your remote git repository before tito will let you build it. (better support for standalone git repositories is coming, for now --offline will help)
To build the most recent .tar.gz for a package, cd into that packages directory and run:
tito build --tgz
Note that this tarball will have a consistent checksum every time.
Likewise the --srpm and --rpm options allow you to build both binary and source rpms.
Add in the --tag=TAG option to build any of the above for any past tag.
If you're working on something locally and would like to check that your package is still building ok without pushing your changes to the remote repository, add the --test option. This will build a test rpm from your most recently committed work. (NOTE: does not include uncommitted changes)
TODO: Document the use of --release, which is complicated and untested against Fedora's Koji.
If you create a tag accidentally or that you wish to re-do, make sure you have not git pushed the tag yet, the auto-commit is the most recent in your git history, and run:
git tag -d YOURNEWTAG git reset --hard HEAD^1
If your project is standalone (no remote reference you communicate with as authoritative) you may wish to set offline = "true" in rel-eng/tito.props under the globalconfig section, so you do not need to specify --offline with each invocation.
Some user specific settings can be defined in ~/.titorc:
Default Location to write temp files, tarballs and rpms to:
RPMBUILD_BASEDIR = /tmp/tito
Specify packages to not auto-install. Uses a simple string contains
NO_AUTO_INSTALL = project-subpkg1 project-subpkg2
The main tito configuration file resides in your git repository at /rel-eng/tito.props. Below is an attempt to document each supported section and option:
default_builder / default_tagger
Specified the default builder to use if the package does not specify it's own in a package specific tito.props.
default_builder = spacewalk.releng.builder.Builder default_tagger = spacewalk.releng.tagger.VersionTagger
Specifies an optional directory where you may be storing custom tito builders/taggers in your git repository. If you have very specific build needs, this can be useful to tailer the core tito classes with inheritance, or to write your own from scratch. Note that this has disadvantages as well, as this code will need to be kept in all your branches, and can have implications when building tags from the past.
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.
tag_suffix = -mysuffix
Tito has support for releasing builds in a CVS driven buildsystem, similar to the former Fedora build infrastructure. (WARNING: this has now been replaced with a git infrastructure, this module no longer can be used with Fedora)
[cvs] cvsroot = :ext:email@example.com:/cvs/extra branches = CVSBRANCH1 CVSBRANCH2
Tito has support for releasing builds in Fedora's git build system. Your spec file and patches will be synched into the first branch listed below, then merged into the following branches.
branches = master f14/master f13/master