ECLEAN

Section: (1)
Updated: 0.4.2-r1
Page Index

NAME

eclean - A cleaning tool for Gentoo distfiles and binary packages.

SYNOPSIS

eclean [global-options] ... <actions> [action-options] ...

eclean-dist [global-options, distfiles-options] ...

eclean-pkg [global-options, packages-options] ...

eclean(-dist,-pkg) [--help, --version]

DESCRIPTION

eclean is small tool to remove obsolete portage sources files and binary packages. Used on a regular basis, it prevents your DISTDIR and PKGDIR directories to infinitely grow, while not deleting files which may still be useful.

By default, eclean will protect all distfiles or binary packages corresponding to some ebuilds available in the Portage tree. This is the safest mode, since it will protect whatever may still be useful, for instance to downgrade a package without downloading its sources for the second time, or to reinstall a package you unmerge by mistake without recompiling it. Sure, it's also a mode in which your DISTDIR and PKGDIR will stay rather big (although still not growing infinitely). For the 'distfiles', this mode is also quite slow because it requires some access to the whole Portage tree.

If you use the --deep option, eclean will only protect files corresponding to some currently installed package (taking their exact version into account). It will save much more space, while still preserving sources files around for minor revision bumps, and binaries for reinstallation of corrupted packages. But it won't keep files for less usual operations like downgrading or reinstalling an unmerged package. This is also the fastest execution mode (big difference for distfiles), and the one used by most other cleaning scripts around like yacleaner (at least in its version 0.3).

Somewhere in the middle, adding the --package-names option when using --deep will protect files corresponding to all existing versions of installed packages. It will allow easy downgrading without recompilation or redownloading in case of trouble, but won't protect you against package uninstallation.

In addition to this main modes, some options allow to declare a few special cases file protection rules:

o: --time-limit is useful to protect files which are more recent than a given amount of time.
o: --size-limit (for distfiles only) is useful if you want to protect files bigger than a given size.
o: --fetch-restricted (for distfiles only) is useful to protect manually downloaded files. But it's also very slow (again, it's a reading of the whole Portage tree data)...
o: Finally, you can list some categories or package names to protect in exclusion files (see EXCLUSION FILES below).

PARAMETERS

Global options

-C, --nocolor turn off colors on output
-d, --deep only keep the minimum for a reinstallation
-e, --exclude-file=<path> path to the exclusion file: <path> is the absolute path to the exclusion file you want to use.
When this option is not used, default paths are /etc/eclean/{packages,distfiles}.exclude (if they exist). Use /dev/null if you have such a file at it standard location and you want to temporary ignore it.
-i, --interactive ask confirmation before deleting
-n, --package-names protect all versions (--deep only)
-p, --pretend only display what would be cleaned
-q, --quiet be as quiet as possible, only display errors
-t, --time-limit=<time> don't delete files modified since <time>: <time> is an amount of time: "1y" is "one year", "2w" is "two weeks", etc.
Units are: y (years), m (months), w (weeks), d (days) and h (hours).
-h, --help display the help screen
-v, --verbose display more verbose messages during processing
-V, --version display version information

Actions

distfiles: Clean files from /usr/portage/distfiles (or whatever else is your DISTDIR in make.conf). This action should be useful to almost any Gentoo user, we all have to big DISTDIRs sometime...
eclean-dist is a shortcut to call eclean with the "distfiles" action, for simplified command-line.
packages: Clean files from /usr/portage/packages (or whatever else is your PKGDIR in make.conf). This action is in particular useful for people who use the "buildpkg" or "buildsyspkg" FEATURES flags.
eclean-pkg is a shortcut to call eclean with the "packages" action, for simplified command-line.

Options for the 'distfiles' action

-f, --fetch-restricted protect fetch-restricted files (--deep only)
-s, --size-limit=<size> don't delete distfiles bigger than <size>: <size> is a size specification: "10M" is "ten megabytes", "200K" is "two hundreds kilobytes",
etc.
Units are: G, M, K and B.

Options for the 'packages' action

-i, --ignore-failure ignore the failure to locate PKGDIR: This is only useful when scripting to ignore an otherwise fatal error.

EXCLUSION FILES

Exclusions files are lists of packages names or categories you want to protect in particular. This may be useful to protect more binary packages for some system related packages for instance. Syntax is the following:

o: blank lines and lines starting with a "#" (comments) are ignored.
o: only one entry per line is allowed.
o: if a line contains a category name, like "sys-apps", then all packages from this category will be protected. "sys-apps/*" is also allowed for aesthetic reasons, but that does NOT mean that wildcard are supported in any way for any other usage.
o: if a line contains a package name ("app-shells/bash"), then this package will be protected. Versioned atoms like ">=app-shells/bash-3" are NOT supported. Also, the full package name (with category) is mandatory.
o: if a line contains a package name with an exclamation mark in front ("!sys-apps/portage"), then this package will be excluded from protection. This is only useful if the category itself was protected.
o: for distfiles protection, a line can also be a filename to protect. This is useful if you have some files which are not registered by the ebuilds, like OpenOffice.org i18n files ("helpcontent_33_unix.tgz" for instance). Another example are sources you want to protect that do not have an ebuild in the tree or any currently installed overlays.
o: eclean will also inform you of any unavailable installed packages that are on your system as well as if it was able to locate the source filename(s) in order to protect them. If you want to protect all installed distfile sources, run eclean in pretend mode first. Then check which sources it was not able to find the filename(s) for and add entries for them in the distfiles.exclude file before running eclean again.

By default, if it exists, /etc/eclean/packages.exclude (resp. distfiles.exclude) will be use when action is "packages" (resp. "distfiles"). This can be override with the --exclude-file option.

EXAMPLES

Clean distfiles only, with per file confirmation prompt:
# eclean -i distfiles

Check which binary packages could be removed, with a no-color display:
# eclean -Cp packages

Clean binary packages of uninstalled packages, but keep all versions of installed ones:
# eclean-pkg -d -n

Clean all distfiles except for installed packages (exact version), those which are less than one month old, bigger than 50MB, or fetch-restricted:
# eclean-dist -d -t1m -s50M -f

From a crontab, silently clean packages in the safest mode, and then distfiles in deep mode but protecting files less than a week old, every Sunday at 1am:
0 1 * * sun eclean -C -q packages ; eclean -C -q -d -t1w distfiles

NOTE

While running and searching distfiles for cleaning, eclean will report any: unavailable packages it finds installed on your system. An unavailable package is a package that is installed on the system, but there is not a corresponding ebuild available. Those sources may not be protected if the SRC_URI is not recorded in the installed package database. The SRC_URI is no longer recorded by recent portage/pkgcore versions.

BUGS

SRC_URI variables ."of ebuilds. It means that if an ebuild uses files that are not part of its SRC_URI, eclean will ."probably remove them. This are ebuilds bugs, please report them as such on ."http://bugs.gentoo.org.

AUTHORS

Thomas de Grenier de Latour (tgl) <degrenier@easyconnect.fr>
modular re-write by:
Brian Dolbec (dol-sen) <brian.dolbec@gmail.com>