man/eclean.1

   1 .TH "eclean" "1" "0.4.1" "gentoolkit"
   2 .SH "NAME"
   3 eclean \- A cleaning tool for Gentoo distfiles and binary packages.
   4 .SH "SYNOPSIS"
   5 .LP
   6 .B eclean \fR[\fIglobal\-options\fR] ... <\fIactions\fR> \fR[\fIaction\-options\fR] ...
   7 .LP
   8 .B eclean\-dist \fR[\fIglobal\-options, distfiles\-options\fR] ...
   9 .LP
  10 .B eclean\-pkg \fR[\fIglobal\-options, packages\-options\fR] ...
  11 .LP
  12 .B eclean(-dist,-pkg) \fR[\fI\-\-help, \-\-version\fR]
  13 .SH "DESCRIPTION"
  14 \fBeclean\fP is small tool to remove obsolete portage sources files and binary packages.
  15 Used on a regular basis, it prevents your DISTDIR and PKGDIR directories to
  16 infinitely grow, while not deleting files which may still be useful.
  17 .PP
  18 By default, eclean will protect all distfiles or binary packages corresponding to some
  19 ebuilds available in the Portage tree.  This is the safest mode, since it will protect
  20 whatever may still be useful, for instance to downgrade a package without downloading
  21 its sources for the second time, or to reinstall a package you unmerge by mistake
  22 without recompiling it.  Sure, it's also a mode in which your DISTDIR and PKGDIR will
  23 stay rather big (although still not growing infinitely).  For the 'distfiles', this
  24 mode is also quite slow because it requiries some access to the whole Portage tree.
  25 .PP
  26 If you use the \-\-destructive option, eclean will only protect files corresponding to
  27 some currently installed package (taking their exact version into account).  It will
  28 save much more space, while still preserving sources files around for minor revision
  29 bumps, and binaries for reinstallation of corrupted packages.  But it won't keep files
  30 for less usual operations like downgrading or reinstalling an unmerged package.  This
  31 is also the fastest execution mode (big difference for distfiles), and the one used by
  32 most other cleaning scripts around like yacleaner (at least in its version 0.3).
  33 .PP
  34 Somewhere in the middle, adding the \-\-package\-names option when using \-\-destructive
  35 will protect files corresponding to all existing versions of installed packages.  It will
  36 allow easy downgrading without recompilation or redownloading in case of trouble, but
  37 won't protect you against package uninstallation.
  38 .PP
  39 In addition to this main modes, some options allow to declare a few special cases file
  40 protection rules:
  41 .IP o
  42 \-\-time-limit is useful to protect files which are more recent than a given amount of time.
  43 .IP o
  44 \-\-size-limit (for distfiles only) is useful if you want to protect files bigger than  a given size.
  45 .IP o
  46 \-\-fetch-restricted (for distfiles only) is useful to protect manually downloaded files.
  47 But it's also very slow (again, it's a reading of the whole Portage tree data)...
  48 .IP o
  49 Finally, you can list some categories or package names to protect in exclusion files (see
  50 \fBEXCLUSION FILES\fP below).
  51 .SH "PARAMETERS"
  52 .SS "Global options"
  53 .TP
  54 \fB\-C, \-\-nocolor\fP                          turn off colors on output
  55 .TP
  56 \fB\-d, \-\-destructive\fP                      only keep the minimum for a reinstallation
  57 .TP
  58 \fB\-e, \-\-exclude\-file=<path>\fP     path to the exclusion file
  59 \fB<path>\fP is the absolute path to the exclusion file you want to use.
  60 When this option is not used, default paths are /etc/eclean/{packages,distfiles}.exclude
  61 (if they exist).  Use /dev/null if you have such a file at it standard location and
  62 you want to temporary ignore it.
  63 .TP
  64 \fB\-i, \-\-interactive\fP          ask confirmation before deleting
  65 .TP
  66 \fB\-n, \-\-package\-names\fP       protect all versions (\-\-destructive only)
  67 .TP
  68 \fB\-p, \-\-pretend\fP              only display what would be cleaned
  69 .TP
  70 \fB\-q, \-\-quiet\fP                be as quiet as possible, only display errors
  71 .TP
  72 \fB\-t, \-\-time-limit=<time>\fP    don't delete files modified since <time>
  73 \fB<time>\fP is an amount of time: "1y" is "one year", "2w" is "two weeks", etc.
  74 .br
  75 Units are: y (years), m (months), w (weeks), d (days) and h (hours).
  76 .TP
  77 \fB\-h, \-\-help\fP                 display the help screen
  78 .TP
  79 \fB\-v, \-\-verbose\fP              display more verbose messages during processing
  80 .TP
  81 \fB\-V, \-\-version\fP              display version informations
  82 .SS "Actions"
  83 .TP
  84 \fBdistfiles\fR
  85 Clean files from /usr/portage/distfiles (or whatever else is your DISTDIR in /etc/make.conf).
  86 This action should be useful to almost any Gentoo user, we all have to big DISTDIRs sometime...
  87 .br
  88 \fBeclean\-dist\fP is a shortcut to call eclean with the "distfiles" action, for simplified
  89 command\-line.
  90 .TP
  91 \fBpackages\fR
  92 Clean files from /usr/portage/packages (or whatever else is your PKGDIR in /etc/make.conf).
  93 This action is in particular useful for people who use the "buildpkg" or "buildsyspkg"
  94 FEATURES flags.
  95 .br
  96 \fBeclean\-pkg\fP is a shortcut to call eclean with the "packages" action, for simplified
  97 command\-line.
  98 .SS "Options for the 'distfiles' action"
  99 .TP
 100 \fB\-f, \-\-fetch-restricted\fP         protect fetch-restricted files (\-\-destructive only)
 101 .TP
 102 \fB\-s, \-\-size-limit=<size>\fP        don't delete distfiles bigger than <size>
 103 <size> is a size specification: "10M" is "ten megabytes", "200K" is "two hundreds kilobytes",
 104 etc.
 105 .br
 106 Units are: G, M, K and B.
 107 .SS "Options for the 'packages' action"
 108 .TP
 109 There is no specific option for this action.
 110 .SH "EXCLUSION FILES"
 111 Exclusions files are lists of packages names or categories you want to protect
 112 in particular.  This may be useful to protect more binary packages for some system
 113 related packages for instance.  Syntax is the following:
 114 .IP o
 115 blank lines and lines starting with a "#" (comments) are ignored.
 116 .IP o
 117 only one entry per line is allowed.
 118 .IP o
 119 if a line contains a category name, like "sys\-apps", then all packages from this
 120 category will be protected.  "sys\-apps/*" is also allowed for aesthetic reasons, but
 121 that does NOT mean that wildcard are supported in any way for any other usage.
 122 .IP o
 123 if a line contains a package name ("app\-shells/bash"), then this package will be
 124 protected.  Versioned atoms like ">=app\-shells/bash\-3" are NOT supported.  Also, the
 125 full package name (with category) is mandatory.
 126 .IP o
 127 if a line contains a package name with an exclamation mark in front ("!sys\-apps/portage"),
 128 then this package will be excluded from protection.  This is only useful if the category
 129 itself was protected.
 130 .IP o
 131 for distfiles protection, a line can also be a filename to protect. This is useful if you have
 132 some files which are not registered by the ebuilds, like OpenOffice.org i18n files
 133 ("helpcontent_33_unix.tgz" for instance).  Another example are sources you want to protect
 134 that do not have an ebuild in the tree or any currently installed overlays.
 135 .IP o
 136 eclean will also inform you of any deprecated installed packages that are on your system as well
 137 as if it was able to locate the source filename(s) in order to protect them.  If you want to protect
 138 all installed distfile sources, run elcelan in pretend mode first.  Then check which sources it was
 139 not able to find the filename(s) for and add entries for them in the distfiles.exclude file before
 140 running eclean again.
 141 .LP
 142 By default, if it exists, /etc/eclean/packages.exclude (resp. distfiles.exclude) will be use
 143 when action is "packages" (resp. "distfiles").  This can be overide with the \-\-exclude\-file
 144 option.
 145 .SH "EXAMPLES"
 146 .LP
 147 Clean distfiles only, with per file confirmation prompt:
 148 .br
 149 .B # eclean \-i distfiles
 150 .LP
 151 Check which binary packages could be removed, with a no-color display:
 152 .br
 153 .B # eclean \-Cp packages
 154 .LP
 155 Clean binary packages of uninstalled packages, but keep all versions of installed ones:
 156 .br
 157 .B # eclean-pkg \-d \-n
 158 .LP
 159 Clean all distfiles except for installed packages (exact version), those which
 160 are less than one month old, bigger than 50MB, or fetch-restricted:
 161 .br
 162 .B # eclean-dist \-d \-t1m -s50M -f
 163 .LP
 164 From a crontab, silently clean packages in the safest mode, and then distfiles in destructive
 165 mode but protecting files less than a week old, every sunday at 1am:
 166 .br
 167 .B 0 1 * * sun \ \ eclean \-C \-q packages ; eclean \-C \-q \-d \-t1w distfiles
 168 .SH "NOTE"
 169 .TP
 170 While running and searching distfiles for cleaning, elcean will report any deprecated packages
 171 it finds installed on your system.  Those sources may not be protected if the SRC_URI is not recorded
 172 in the installed package database.  The SRC_URI is no longer recorded by recent portage/pkgcore versions.
 173 .".SH "BUGS"
 174 .".TP
 175 ."The policy used to decide if a distfile can be removed or not relies on the 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.
 176 .".TP
 177 ."In safest mode (default, without the \-\-destructive option), this script can be very slow.  There
 178 ."is not much to do about it without hacking outside of the portage API.
 179 .SH "SEE ALSO"
 180 .TP
 181 The Gentoo forum thread that gave birth to eclean:
 182 .B http://forums.gentoo.org/viewtopic.php?t=3011
 183 .TP
 184 The bug report requesting eclean inclusion in gentoolkit:
 185 .B http://bugs.gentoo.org/show_bug.cgi?id=33877
 186 .SH "AUTHORS"
 187 Thomas de Grenier de Latour (tgl) <degrenier@easyconnect.fr>
 188 .br
 189 modular re-write by:
 190 .br
 191 Brian Dolbec (dol-sen) <brian.dolbec@gmail.com>