**********
Important:
**********
gatt is still under heavy development and may therefore contain nasty bugs.
Please make backups of "/etc/make.conf" and "/etc/portage/*" before you
start working with the tool. You have been warned!
********
Summary:
********
gatt is a small console application that is targeted at gentoo arch testers.
It does so by providing a command line interface to operations that should
ease and simplify working on stabilisation bugs. It seems to be most
effective to describe this by an illustrative example:
Let's say you want to work an bug xyz that has the summary "please stabilize
app-foo/bar-1.2-r4". Without gatt, you will most likely do the following:
-) echo "=app-foo/bar-1.2-r4" >> /etc/portage/package.keywords
-) make sure test and collision-protect is activated
-) emerge -av app-foo/bar
Using gatt, all you need is to type
-) gatt -w xyz
into your terminal. Before we proceed, let's take a look at
"/etc/portage/package.keywords"
(or /etc/portage/package.keywords/gatt.keywords if package.keywords
happens to be a directory). It will now contain a section like
this one:
###### for bug xyz {
## attribute: keep
=app-foo/bar-1.2-r4
###### }
Now you will most certainly wonder about the line that starts with
"## attribute". We will come to that later. For now, imagine, that
there is some stable package app-baz/redp-0.6,
that depends on app-foo/bar, and that you want to make sure that
it still works, even with the newer version of bar. Let's assume
further, that you don't use redp normally, and that therefore it
is not installed. Now, type
-) gatt -w xyz app-baz/redp-0.6
instead of
-) emerge -av app-baz/redp
After gatt has finished, you will find this section in your
keywords file:
###### for bug xyz {
## attribute: keep
=app-foo/bar-1.2-r4
## attribute: unmerge
=app-baz/redp-0.6
###### }
As bar seems to be OK and plays nicely with redp, finally
the bug gets resolved, and app-foo/bar-1.2-r1 now has a shiny, new
stable keyword for your arch. You as tester however want to keep
your box and keyword files clean. Without gatt but a healthy
memory, you would most likely do the following:
-) emerge -Ca app-baz/redp
-) remove the entry for app-foo/bar from your keyword file
If you type "emerge -uavDN world" a bit later, you may notice that
portage wants to downgrade app-foo/bar again, because you have not yet
synced, or the stable keyword is not yet distributed to the
rsync mirrors. But this is not what you want, so you can either
wait a few hours and "emerge --sync" again, or modify your package
file. Both is annoying and not necessary with gatt: By typing
-) gatt -r xyz
into your terminal, gatt will
a.) unmerge app-baz/redp for you.
b.) make sure app-foo/bar-1.2-r4 stays in your keyword file if needed.
The relevant section now looks like this:
###### slated {
## attribute: keep
=app-foo/bar-1.2-r4
###### }
As soon as app-foo/bar-1.2-r4 is stable on your very own box, and not only
in cvs, "gatt -c" will automatically remove all unneeded and only
unneeded slated entries.
Now, as promised, let's look at "## attribue: XXX":
At the moment there are three different attributes that are understood
by gatt. These are "keep", "unmerge" and "remerge". "keep" tells gatt,
that you want to keep the associated package installed and is automatically
set if you upgrade a package for testing.
"unmerge" tells gatt that the associated package has been installed
for testing purposes only and that you don't want to keep the package once
you are finished with testing. "unmerge" is chosen by gatt without any
further intervention for packages that have not been installed
on your system before you called gatt. Note that gatt also
considers SLOT in this case. Thus, if you have gtk-2* installed, gatt will
use "unmerge" for gtk-1* if you had a gtk-1* free system before.
Finally "remerge" tells gatt to remerge the latest stable version of the
package (if any). Please don't use this attribute for now, as its
implementation may result in emerge returning an error message
at the moment.
While gatt chooses attributes for you automatically, feel
free to change them manually if they don't fit.
gatt can do a few things more, like handling masked packages and resolving
needed unstable dependencies. You can also use gatt as (limited) euse
replacement. "gatt --help" should give you a brief overview.
***************************
Known bugs and limitations:
***************************
As already stated at the beginning, gatt is still under development
and not feature complete. Thus, there are a view options already
listed in "gatt -h" that are not implemented. gatt will refuse to
do anything if you try these options.
It is not yet possible to launch multiple instances of gatt
that do emerge related stuff, as this may lead to undefined behaviour
for the time being.
If gatt is terminated by a signal, it is not unlikely that you find
a line like this in your package files:
"###### added temporary by gatt - you may have found a bug in gatt"
If you haven't already added stuff of your own below this line, you can
safely remove this line and everything that comes after it. Besides,
if gatt has modified your make.conf (it only adds "collision-protect"
and "test" to "FEATURES" if needed), these modifications are not
undone. Implementing at least a SIGTERM handler is planned.
gatt will refuse to work, if it encounters packages that are masked
by profile or missing keyword. Fixing this is planned.
Although you can use gatt to work on bugs that include dozens of packages
waiting for stable keywords (think of "stable gnome-2.16.1"), it doesn't
scale well in this situation. While changing this is on the todo list,
it is not yet clear how to do this in detail.
While gatt is targeted to be most useful for every arch team, at the
moment its primary target is x86.
"## attribute: remerge" needs a more sophisticated implementation.
Don't use it for now.
gatt is not a package manager. Therefore, it is possible that gatt
removes dependencies that are required by other installed packages.
gatt depends on unstable packages.