Gatt gives you the possibility of reusing the information it extracted during its operations. Special variables are recognized in a given plain-text file, called template, and filled with appropriate values. Thus you can specify further actions based on these information. For example, your template can be a Bash script which is then parsed by Gatt for some special variable names that are given the correct value. The script then marks stable the packages you tested and that were marked testing (also known as ~arch) before.
All used variables start with GATT_ (note the underscore) and can be used in a template just like normal variables. They should be declared at the beginning of your template and set to <gatt-define> (note the brackets). Their initial value will then be exchanged with the correct value from Gatt. The following list of all recognized variables contains some example values which are taken from the package atom app-portage/gatt-0.5.0-r2.
Due to a serious flaw in the way that Gatt evaluates the ordering in which the scripts are executed when dealing with multiple packages, you should better not use this functionality for tree modifying templates for now. Unless you really know what you are doing. Also note, that currently, Gatt is not meant to catch all unstable dependencies of an unstable package. However if using Gatt together with USE=libpaludis (to be found in the Gentoo package sys-apps/paludis, needs to be specified when compiling Gatt and manually unmasked), Gatt will at least warn you, if there are missing unstable dependencies.
Above issues occur if you run several times on the same bugs and proceed
the gatt command with different USE="..." settings. Correct
order for scripts is only preserved if you use the right USE="..."
prefix on all command invocations.
If several packages have to be unmasked (either by the package.keywords or package.unmask file) for one bug they are grouped together. For every single package the template is processed once, thus resulting in a number of scripts equal to the number of unmasked packages. A master script is meant to, but currently may fail to do so, call all individual ones in the order of correct dependency resolution (so you won't make repoman cry when you start doing actual changes in the tree). If there is only one package, no subscripts are needed, so the contents goes into the master script.
The naming scheme for the scripts is the following:
Keep in mind that you generate the scripts for immediate use, because the Portage tree is constantly moving. So information extracted at time A may be outdated and do harm when scripts are executed at time B.
The scripts are made executable for everyone (to ease use in a chrooted environment), where all arguments given to the master script are handed over to each script.
Some templates are shipped with Gatt and are on the one hand examples to create your own and on the other usable out of the box, see Examples.
This is no implementation description as the template itself is well commented, but for the user interface of the generated scripts. To understand the code fully, you should have deep insight into the stabilisation process of Gentoo and know quite a bit about the work-flow of a Gentoo developer. It automates a lot to be really usable and take over some routine tasks, resulting in a quite complex shell script.
Be warned though that architectures, that have not the same Bugzilla alias as their KEYWORD, are not supported (for example the BSDs).
This template will lead to a script that can handle stabilisations and keywording. It automatically detects what type of KEYWORDS to add (either ~arch or arch), and if it is a security bug. The ChangeLog message is set in an appropiate way and everything committed. It then removes the processed arch from the bug's cc field and closes the bug if needed.
The following packages are needed for proper operation
sys-apps/util-linuxwww-client/pybugz>=app-portage/gentoolkit-dev-0.2.6.5Another needed setting is the variable PORTDIR_CVS which contains
the path to the gentoo-x86 tree. So for an ebuild path
/home/user/gentoo-x86/app-category/pkg/pkg-1.0.ebuild
the setting PORTDIR_CVS=/home/user/gentoo-cvs/gentoo-x86 is needed.
Apart from the automatic setting of ChangeLog entry and bug message, the generated script allows to override these by command-line options. These are global for all subscripts, while you can still call all individual ones with the exact same options as the master script. Note however that an addition about closing a bug is always appended.
Some internals of the script can be controlled by global environment variables.
All variables that are available in the script (see Templates) can be used in the external variables, but proper escaping is needed.
Note however, that command-line options modifying above two messages will always override settings through environment variables and internal code.
When operating the script exits with one of the following codes. Be aware that they may change with every new revision of the template.
0123456789101120