tito/README.mkd

ABOUT
=====

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. 


GETTING STARTED
===============

From your git repository:

    tito init

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.


TAGGING PACKAGES
================

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)


BUILDING PACKAGES
=================

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.


TROUBLESHOOTING
===============

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.


CONFIGURATION
=============

Some user specific settings can be defined in ~/.titorc:

# Default Location to write temp files, tarballs and rpms to:
RPMBUILD_BASEDIR = "/tmp/tito"